HarperFast / HarperFast/harper

MCP: refactor operations tool registration so input schemas are introspectable/validatable JSON Schema

Open
#878 0 comments 0 reactions 1 assignee Claimed by @kylebernhardy View on GitHub
area:mcp area:operations-api enhancement feature:mcp-v1
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

Open the contributing guide

Assessment

This issue has not been assessed yet.

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.