Repository navigation
Closed
Labels
enhancementNew feature or requestNew feature or request
Description
Summary
Add a mechanism to author MCP server general instructions, prompts and resources as markdown files under a content directory in this repository, embedded into the stackql binary at build time via go:embed and published through the existing MCP server surface. The existing write_safe_select prompt (currently a Go string constant) would move into this framework as the first migrated item.
This is additive only. No changes to tool registration, tool behaviour, the policy gate, audit, bundling or distribution. The MCPB packaging, registry listings and install paths are unaffected as the content ships inside the binary.
Motivation
- The MCP
initializeresult supports a server-authoredinstructionsstring which conformant hosts inject into model context. This is the sanctioned way to ship dialect and usage guidance (routing semantics ofregion,INclause fan-out behaviour, quoting of hyphenated params, aggregate alias limitations inORDER BY, discovery-before-query workflow) so agents do not burn turns on syntax discovery. There is currently no way to author or ship this content. - Prompts are currently defined inline in Go (
registerPromptsinpkg/mcp_server/server.gowith the body in a string constant). Adding a prompt requires a code change, review of Go source and a rebuild cycle. Prompt content is documentation and should be authored as markdown. - The server registers no MCP resources today. Reference content (SQL dialect notes, per-provider auth guidance) is a natural fit for the resources primitive, letting hosts and users attach depth on demand while
instructionsstays short.
Proposed design
Directory layout
pkg/mcp_server/content/
instructions/
00-dialect.md
10-discovery-workflow.md
20-error-recovery.md
prompts/
write_safe_select.md
regional_inventory.md
resources/
sql-dialect.md
auth-aws.md
Embedded with:
//go:embed content
var contentFS embed.FSInstructions
- All files under
content/instructions/are concatenated in lexical filename order (numeric prefixes control ordering) into a single string. - The result is passed as the server
Instructionsat construction, surfaced in theinitializeresult. - Config addition:
disable_instructions(bool, default false) to suppress publication entirely, consistent with existing opt-out patterns.
Prompts
- Each file under
content/prompts/defines one prompt. YAML frontmatter carries metadata, body carries the prompt text:
---
name: regional_inventory
description: Count or list resources across multiple regions using IN clause fan-out.
arguments:
- name: provider
description: stackql provider (eg awscc)
required: true
- name: regions
description: comma separated region list
required: true
---
Use the {{provider}} provider ... WHERE region IN ({{regions}}) ...{{argument}}placeholders in the body are substituted fromprompts/getarguments.- Registration replaces the current inline mechanism:
registerPromptsiterates the embedded directory instead of hardcoded definitions. ExistingEnabledPromptsconfig gating applies unchanged (nil/empty -> all published). write_safe_selectmoves tocontent/prompts/write_safe_select.mdwith identical name, description and body, so no observable change for existing clients.
Resources
- Each file under
content/resources/defines one resource. Frontmatter carriesname,descriptionand optionaluri(defaultstackql://docs/<filename-without-extension>),mimeTypedefaults totext/markdown. - Served via
resources/listandresources/read. Theresourcescapability is only declared ininitializewhen at least one resource is present and enabled. - Config addition:
enabled_resources(list, same semantics asenabled_prompts: nil/empty -> all published).
Shared loader
- One loader package parses frontmatter + body, validates required fields, and fails the build (via a unit test over the embedded FS) on malformed content, duplicate names or unresolved argument placeholders. Content errors surface at CI time, not at runtime.
Non-goals
- No changes to tools, tool schemas, the policy gate, audit sink or render layer.
- No changes to MCPB packaging, manifests, registry metadata or any distribution channel.
- No runtime loading from disk. Embed only. A user-supplied overlay directory could be a follow-up issue but is out of scope here.
- No templating engine beyond simple
{{name}}substitution.
Acceptance criteria
-
content/instructions/*.mdconcatenated and published asinstructionsin theinitializeresult, suppressible via config -
content/prompts/*.mdpublished viaprompts/list/prompts/getwith argument substitution, gated byEnabledPrompts -
content/resources/*.mdpublished viaresources/list/resources/read, capability declared only when non-empty, gated byenabled_resources -
write_safe_selectmigrated tocontent/prompts/write_safe_select.md;prompts/listandprompts/getoutput byte-identical to current behaviour for this prompt - Adding a new instruction, prompt or resource requires only adding a markdown file (no Go changes)
- Unit tests validate all embedded content parses and required frontmatter fields are present
- Existing tool surface verified unchanged (
tools/listoutput identical before and after) - Binary size delta noted in the PR (expected negligible for markdown content)
Verification
- MCP Inspector against the stdio binary: confirm
instructionsininitialize, prompt enumeration and argument substitution, resource enumeration and read - Claude Code: prompts appear as
/mcp__<server>__<prompt>slash commands; resources attachable - Claude Desktop: prompts appear under the connector attachment menu
- Regression: existing clients configured with
enabled_promptscontinue to see filtered sets
Metadata
Metadata
Assignees
Labels
enhancementNew feature or requestNew feature or request
Activity
feat: embedded content framework for MCP instructions, prompts and re…
jeffreyaven commentedon Jul 31, 2026
closed with #697