Repository navigation
docs(mcp): document saved queries, test sequences and the ERD surface - #321
Merged
Merged
Conversation
server-instructions.ts is the single source of truth for agent-facing guidance (#529), and it described .bas/.cls modules, form and report layouts, event wiring and test manifests — but none of the saved-query, test-sequence or Access ERD extractors the fork already ships. An agent that is never told `query` nodes exist greps the .sql instead, which is the read-fallback this project's retrieval work exists to prevent. Add the three surfaces in the shape the existing entries use: the file shape that produces them, the node kinds and edges emitted, and the provenance tag to filter on. The new suite asserts nothing about wording. It runs the real extractors, collects the node kinds and synthesizedBy tags they emit, and requires the instructions to name each one, so renaming a tag in an extractor fails the build until the guidance follows. The ERD case uses the checked-in fixture, which carries both a plain and a LINKED table, so both tags are exercised rather than assumed. Refs #320
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Closes #320
What was missing
src/mcp/server-instructions.tsis the single source of truth for agent-facing guidance (#529) — the first and only thing an agent is told about what this index holds. It documented.bas/.clsmodules,.form.txt/.report.txtlayouts, event wiring, call-edge shape and test manifests, and said nothing about three extractors the fork already ships:queries/<Name>.sql+ siblingqueries.jsonquerynode (languagesql) +referencesto tables (sql-query-table,vba-external-backend)sequences/*.jsonfilenode +referencesto eachTest_*(vba-test-sequence, withrunnerPolicy/sequenceFile/procedureIndex)ERD/*.mdclassnodes (access-erd-table), fieldtype_member+contains, linked-tablereferences(vba-linked-table)This is the read-fallback this project's retrieval work exists to prevent: an agent that has never been told
querynodes exist will grep the.sql. The ERD surface is the cheapest answer to "what columns does this table have" and was reachable only by accident.To be clear about the claim: this is not an argument that new prose changes tool choice — the instructions are a low-salience channel and this repo has measured that. It is the narrower case of telling the agent which node kinds and provenance tags are in the index, so it can use what a call already returns.
How it is kept honest
The new suite asserts nothing about wording. For each surface it runs the real extractor, collects every node kind and
metadata.synthesizedBytag actually emitted, and requires the instructions to name each one. Rename a tag in an extractor and the build fails until the guidance follows.The ERD case runs against the checked-in fixture, which carries both a plain and a
LINKEDtable, so both tags are exercised rather than assumed. Each test also sanity-checks that the extractor really produced the shape (e.g. aquerynode exists), so an extractor that silently stopped emitting cannot make the test pass by emitting nothing.Verification
src/mcp/server-instructions.tsfails 3 of the 4 new tests, naming the exact undocumented tag each time (sql-query-table,vba-test-sequence,access-erd-table).pnpm exec vitest run vba extraction-sql-query sql-query-discovery— 73 files, 1217 passed, 1 skipped (the Windows CI leg, run locally on Windows). The new file's name containsvba, so that leg picks it up.npx tsc --noEmit— clean.No behavior change, no new tool: instructions text plus its coverage test.