HarperFast / HarperFast/documentation
Re-add the static properties MCP/OpenAPI schema sections once harper#1921 lands
- Dominant language
- MDX
- Stars
- 9
- Forks
- 9
- Avg merge
- 2d 12h
- Merged PRs (30d)
- 32
Description
## Context
[PR #605](https://github.com/HarperFast/documentation/pull/605) originally documented `static properties` as a first-class MCP/OpenAPI schema source. That behavior comes from [harper#1921](https://github.com/HarperFast/harper/pull/1921), which is **still open** (changes requested) — and v5.2.0 through v5.2.6 all shipped without it. The sections were badged `v5.2.0`, which was false for every released version, so they were removed from #605 in `89f9dac1` and the PR was rescoped to shipped behavior only.
Verification, for whoever picks this up:
```
$ git show v5.2.6:components/mcp/tools/application.ts | grep 'const attributes'
const attributes = (ResourceClass?.attributes ?? []) as HarperAttribute[];
$ git show pr1921:components/mcp/tools/application.ts | grep 'const attributes'
const attributes = resolveAttributes(ResourceClass) as HarperAttribute[];
```
`resolveAttributes` is absent from both `components/mcp/tools/application.ts` and `resources/openApi.ts` at `v5.2.6`.
## What needs re-adding once harper#1921 lands
All of this content is still in the branch's history: `cfdbab61` is the last commit before the rescope and remains an ancestor of the PR branch, so `git show cfdbab61:reference/resources/resource-api.md` (and the same for the other files below) recovers the removed text verbatim.
- **`reference/resources/resource-api.md`**, under `static properties`:
- which surfaces derive from it, and which explicitly don't
- the **JSON Schema vocabulary** subsection (lowercase JSON Schema types vs. capitalized GraphQL names; the hazard of a name in neither vocabulary)
- the table of every fragment key Harper reads, with per-surface behavior
- resolution notes for unions, item-less arrays, optional properties, and `static primaryKey`
- the nested-object + array-of-object example
- **`learn/developers/mcp-and-openapi-metadata.mdx`**, Path B: the emitted `tools/list` JSON, the vocabulary warning, the Path-B authoring rubric, and the debugging guidance.
- **`reference/mcp/tool-metadata.md`** and **`reference/mcp/tools-and-resources.md`**: the "schema source is `attributes`, or `static properties` when absent" clause.
- **`reference/mcp/overview.md`**: same clause on the input-schema bullet.
## Blockers and cautions
1. **Badge against the release #1921 actually ships in**, determined per [AGENTS.md](https://github.com/HarperFast/documentation/blob/main/AGENTS.md#versioning-content) — from the core repo's git tags, confirming the feature's files exist at the tag, not from `--contains` or a branch's `package.json`. As of this writing `v5.2.6` is the newest tag and v5.3 is the open line, so this is **not** `v5.2.0`. Note there is no `v5.3` milestone in this repo yet.
2. **[harper#1944](https://github.com/HarperFast/harper/pull/1944) is also open** — it shares one schema emitter so the two surfaces stop diverging. If it lands with or before #1921, the per-surface divergence content (the fragment-key table's asymmetric rows, the nullability and nested-`enum`/`format`/`const` notes) collapses and should be **written against the unified emitter instead of restored as-is**. Derive the text from the merged code, not from either PR's head.
3. Three related core issues change this text if they're fixed: [harper#1940](https://github.com/HarperFast/harper/issues/1940) (already fixed on main — table-less Resources now list to any authenticated user, so the old "super-users only" note must not come back), [harper#1941](https://github.com/HarperFast/harper/issues/1941) (nested `hidden`), [harper#1942](https://github.com/HarperFast/harper/issues/1942) (the two type mappers disagreeing).
## What is already correct on main
Don't redo these — they landed with the rescoped #605:
- REST `id.property` resolving against `static properties` ([harper#1933](https://github.com/HarperFast/harper/pull/1933), shipped v5.2.0), plus the 5.2 release-notes entry.
- `attribute_permissions` does not narrow MCP tool schemas; the tool *list* is filtered by table-level permissions.
- The output-schema contracts: only `get_*` is record-shaped; `create_*` is `{ id }`, `update_*`/`patch_*` are `{ ok }`, `delete_*` is `{ deleted }`, `search_*` has none.
- Path B states the current gap and points at [harper#1923](https://github.com/HarperFast/harper/issues/1923) — **that paragraph is what this issue replaces** when the gap closes.
Contributor guide
Research direction
Read AGENTS.md versioning guidance, then inspect the merged harper#1921 and harper#1944 code and the release tag where it ships. Recover the prior wording from cfdbab61 for the listed reference and learn files, but reconcile it with the unified emitter and related fixes. Done means all listed sections accurately describe the released behavior and carry the correct version badge.
Written by the indexing model from the issue text.
Assessment
- Tech stack
- graphql, openapi
- Domain
- api, documentation
- Issue type
- Documentation
- Difficulty
- 4/5
- Estimated time
- 3-5 days
- Activity status
- Active
- Clarity
- Clearly specified
- Newbie friendliness
- 38/100