HarperFast / HarperFast/harper
MCP: refactor operations tool registration so input schemas are introspectable/validatable JSON Schema
- Dominant language
- JavaScript
- Stars
- 89
- Forks
- 10
- Avg merge
- 2d 6h
- Merged PRs (30d)
- 200
Description
## Context
Follow-up from review of #856 (MCP v1 tools surface).
The operations-profile MCP tools currently get their `inputSchema` from **hand-curated** JSON Schemas in `components/mcp/tools/schemas/operations.ts`, with a `PERMISSIVE_SCHEMA` (`{ type: 'object', additionalProperties: true }`) fallback for any opted-in operation that lacks an entry. This was a deliberate v1 choice — Harper's server-side validators are Joi, which doesn't round-trip cleanly to JSON Schema (documented in the file header).
## Problem
- **Drift risk.** The curated schemas are decoupled from the Joi validators that actually enforce input at dispatch time. As operations evolve, the MCP-advertised schema and the real validation can silently diverge.
- **Coverage gaps.** Operations without a curated entry fall back to a fully permissive schema, giving the LLM no guidance and deferring all feedback to runtime errors.
- **No introspection guarantee.** Nothing asserts the curated schemas are themselves valid JSON Schema (draft-07-ish, per the MCP spec).
## Proposed direction
Refactor operations API registration so the input schema is derived from (or validated against) a single source of truth, and can be introspected as valid JSON Schema. Options to explore:
- Generate JSON Schema from the Joi validators (e.g. a Joi→JSON-Schema conversion step), or
- Migrate operation validation to a schema representation that natively serializes to JSON Schema, or
- At minimum, add a build/test-time assertion that every entry in `OPERATION_INPUT_SCHEMAS` is valid JSON Schema and that curated schemas stay in sync with the server-side validators.
## Acceptance
- Operations tool `inputSchema`s are provably valid JSON Schema (asserted in CI).
- A single source of truth (or an enforced sync check) between MCP-advertised schema and server-side validation.
_Filed by Claude on behalf of @kriszyp during #856 review._
Contributor guide
Assessment
This issue has not been assessed yet.