docs: MCP/OpenAPI metadata authoring for harper#1095#516
Conversation
Document Harper's class-level metadata surface that drives both the MCP
tool descriptors and the OpenAPI document from a single source of truth.
- reference/database/schema.md:
- New "Documenting Types and Fields" section covering GraphQL
"" "" docstring conventions on @table @export types and their fields,
with notes on which MCP/OpenAPI surfaces they reach.
- @hidden directive documented at both type level (under Type
Directives) and field level (under Field Directives), with explicit
framing as metadata-visibility — not access control.
- Trust-model note: docstrings reach LLMs and public OpenAPI
consumers verbatim; treat them as code.
- reference/resources/resource-api.md:
- New "Class-level metadata for MCP and OpenAPI" section covering
static description, static properties (Record), static outputSchemas
(per-verb overrides), static hidden, static mcp.annotations (narrow
MCP override), and static mcpTools (custom non-verb methods).
- Inheritance pattern: extending @table @export Resources composes via
spread (static properties = { ...Parent.properties, foo: {...} }).
- Under-annotate-before-mis-annotate note for idempotentHint.
- learn/developers/mcp-and-openapi-metadata.mdx (new):
- Full how-to with before/after MCP tools/list output.
- GraphQL-first path for @table @export Resources.
- Programmatic Resource path for class-statics authoring.
- Inheritance example, @hidden example, RBAC notes, verification steps.
- reference/mcp/tool-metadata.md (new):
- Per-profile sourcing reference for every tool-descriptor field
(operations vs application, verb tools vs custom mcpTools).
- Sample descriptors for get_Product (with docstrings) and add_user.
- Catalog of harper://* synthetic resources.
Companion to HarperFast/harper feat-mcp-metadata-1095 (the
implementation PR).
Co-Authored-By: Claude Opus 4.7 <noreply@anthropic.com>
![gemini-code-assist[bot]](https://avatars.githubusercontent.com/in/956858?s=60&v=4){kind=small}
There was a problem hiding this comment.
Code Review
This pull request adds comprehensive documentation and reference guides for authoring Model Context Protocol (MCP) and OpenAPI metadata in Harper, covering GraphQL docstrings, class-level statics, and the @hidden directive. The review feedback suggests minor improvements to the documentation files, such as removing unused imports in the MDX guide, resolving duplicate headers in the schema reference to avoid fragile auto-generated anchors, and replacing an incomplete placeholder type in the Resource API reference with a more descriptive type.
Important
The consumer version of Gemini Code Assist on GitHub is being sunset. Starting June 18, 2026, new organization installations will be blocked, and all code review activity will officially cease on July 17, 2026.
For more details on the timeline and next steps, please review the Help Documentation.
Prettier --check on Docusaurus' configured profile flagged style issues across all four files in the docs PR. No content changes — just spacing, indentation, and line-break conventions to match the existing repo style. Co-Authored-By: Claude Opus 4.7 <noreply@anthropic.com>
Docusaurus's strict broken-link check rejected relative paths that resolved without the /v5/ versioning prefix the existing docs use. Switched the two inter-doc links to absolute paths matching the established pattern. Co-Authored-By: Claude Opus 4.7 <noreply@anthropic.com>
🚀 Preview DeploymentYour preview deployment is ready! 🔗 Preview URL: https://preview.harper-documentation.harperfabric.com/pr-516 This preview will update automatically when you push new commits. |
Five medium-priority polish findings: 1. Removed unused Tabs / TabItem imports from learn/developers/mcp-and-openapi-metadata.mdx — no <Tabs> usage in the guide. 2. Disambiguated the type-level @hidden header from the field-level one in reference/database/schema.md to prevent the duplicate TOC entries and fragile #hidden / #hidden-1 anchors Docusaurus auto-generates. Now `@hidden (Type Directive)` and `@hidden (Field Directive)`. 3. Updated the intra-doc link from #hidden-1 to #hidden-field-directive to match the new explicit anchor. 4. Replaced the placeholder `ReadonlyArray<...>` type signature for `static mcpTools` in reference/resources/resource-api.md with a descriptive type name `McpToolDefinition[]`. Co-Authored-By: Claude Opus 4.7 <noreply@anthropic.com>
🚀 Preview DeploymentYour preview deployment is ready! 🔗 Preview URL: https://preview.harper-documentation.harperfabric.com/pr-516 This preview will update automatically when you push new commits. |
Ethan-Arrowood
left a comment
Ethan-Arrowood
left a comment
There was a problem hiding this comment.
I like it! Lets make sure your new section is actually showing up in the navigation
There was a problem hiding this comment.
Looks like we have a new section! Nice! This needs to be added to the /reference/index.md and sidebarsReference.ts. All sections also have an overview.md. This technically doesn't have to be a requirement so I'm happy to let this section be hip and cool and break the mold... But yeah may be worth doing an overview.md here to share high-level information for the feature and then have this file too for more detail around too metadata specifically.
* docs(v5.1): release notes, deployment tracking ops, deploy_component updates - Add 5.1.md release notes covering: models/AI, @embed directive, MCP server, deployment tracking, HNSW int8 quantization, and replication improvements - Update deploy_component docs: urlPath, install_allow_scripts params, deployment_id response - Document new deployment operations: list_deployments, get_deployment, get_deployment_payload, delete_deployment_payload - Document hdb_deployment record schema (fields, phases, peer_results) Note: models/AI detail, MCP reference, and HNSW quantization have separate PRs (#523, #507/#516, #508) — this PR adds the release notes overview and the deployment tracking operations which had no coverage. Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com> * style: run prettier on changed files Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com> * fix: remove cross-plugin MCP link that breaks Docusaurus build The release-notes and reference doc plugins are separate; relative .md links between them resolve incorrectly. Removing until PR #507 (MCP reference section) merges and can be linked with an absolute path. Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com> * docs(5.1): expand release notes — middleware/routing, caching, LOCAL_ONLY, HARPER_CONFIG, RocksDB, migrateOnStart, upgrade improvements --------- Co-authored-by: Claude Sonnet 4.6 <noreply@anthropic.com>
2 participants
Summary
Docs sibling for HarperFast/harper#1095 (implementation: HarperFast/harper#1167). Documents the class-level metadata surface that drives both the MCP tool descriptors and the OpenAPI document from a single set of statics.
reference/database/schema.md— new "Documenting Types and Fields" section covering"""docstring"""conventions on@table @exporttypes and fields;@hiddendirective documented at both type level and field level, with explicit framing as metadata-visibility (not access control). Trust-model note that docstrings reach LLMs and public OpenAPI consumers verbatim.reference/resources/resource-api.md— new "Class-level metadata for MCP and OpenAPI" section coveringstatic description,static properties(Record),static outputSchemas,static hidden,static mcp.annotations, andstatic mcpTools. Inheritance pattern via spread. Under-annotate-before-mis-annotate note foridempotentHint.learn/developers/mcp-and-openapi-metadata.mdx— how-to with before/after MCPtools/listoutput; GraphQL-first path; programmatic-Resource path; inheritance example;@hiddenexample; RBAC notes; verification steps.reference/mcp/tool-metadata.md— per-profile sourcing reference for every tool-descriptor field; sample descriptors forget_Productandadd_user; catalog ofharper://*synthetic resources.Where to put attention
The content claims behaviors that should match the implementation PR. Worth spot-checking:
get_ProductoutputSchemaJSON in the how-to — generated structure should match what harper#1167'sderiveGetOutputSchemaactually emits.add_usersample inreference/mcp/tool-metadata.md— uses a curated description; should match the catalog entry that ships with harper#1167.idempotentHintis omitted onadd_*/create_*— should match harper#1167's IDEMPOTENT_OPERATIONS set (currently empty).Should ride with the implementation PR
Don't merge ahead of harper#1167; the docs reference APIs that don't exist until that lands. After Kris approves both, order doesn't matter.
🤖 Generated with Claude Code using model claude-opus-4-7.