feat(mcp): add server-level instructions - #15
Merged
Conversation
Supply MCP clients with rationale and tool-picking guidance via the protocol's server-level `instructions` field. Today the MCP server was constructed without instructions, so agents had no cross-tool orientation — only isolated per-tool descriptions. The composer emits a core block for the example-search workflow unconditionally, plus a package-tools section when the capability predicate is open. Each bullet in the package-tools section is gated on its own backing service so half-open configurations never advertise an unregistered tool. Tool registration and instruction composition now import the same `isPackageToolsCapabilityOpen` predicate, preventing drift between what the server advertises and what it documents. The test file asserts the mention↔registration invariant across gate-closed, gate-open, half-open, and opaque-token scenarios. Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
jlitola
added a commit
that referenced
this pull request
Apr 20, 2026
Follow-up to the server-level `instructions` composer merged in #15: add a one-line bullet for `package_vulnerabilities` in the package-tools section, gated on the same `packageIntelligenceService` presence check as `package_summary`, so the mention↔registration invariant stays tight in every service-wiring permutation. Test updates: - KNOWN_TOOLS gains `package_vulnerabilities` so the invariant loop probes it alongside the other package tools. - Existing half-open / gate-open / opaque-token scenarios re-verify the mention↔registration symmetry without new scenarios. - Gate-closed and "both services wired" assertions gain explicit `package_vulnerabilities` presence / absence checks. Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
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
1 participant
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.
Summary
instructions, leaving agents with no cross-tool orientation — only isolated per-tool descriptions. This PR supplies a terse, composable instructions string via the protocol'sServerOptions.instructionsfield.search/search_language/feedbackworkflow. A package-tools section is appended when the capability predicate is open, with each bullet individually gated on its backing service so half-open configurations never advertise an unregistered tool.isPackageToolsCapabilityOpenpredicate, eliminating drift between what the server advertises and what it documents. Future package-tool PRs extend the composer with one bullet gated on the new service.Design notes
description. Combined gate-open footprint is ~180 tokens; gate-closed is ~95 tokens.mcp-instructions.test.tsasserts both directions (mentioned-implies-registered, and registered-package-tool-implies-mentioned) across six scenarios covering gate-closed, gate-open, both half-open service configurations, and the opaque-token path.docs/implementation/tools.mdclaimed both MCP entry points calledrequireAuth(), which no longer matches the actual code path. Corrected alongside the new Server-instructions section since the doc was already open for the same change.Test plan
bun test— 690 pass, 0 fail (was 685 before)bun run typecheck— cleanbun run lint— no new findings (pre-existingnoExplicitAnywarnings ongetMcpToolDefinitionsuntouched)createMcpServer(deps)constructs successfully in gate-closed and gate-open deps fixtures