Skip to content

[FEATURE] Add embedded content framework for MCP server instructions, prompts and resources #696

Closed

Description

@jeffreyaven

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 initialize result supports a server-authored instructions string which conformant hosts inject into model context. This is the sanctioned way to ship dialect and usage guidance (routing semantics of region, IN clause fan-out behaviour, quoting of hyphenated params, aggregate alias limitations in ORDER 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 (registerPrompts in pkg/mcp_server/server.go with 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 instructions stays 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.FS

Instructions

  • 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 Instructions at construction, surfaced in the initialize result.
  • 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 from prompts/get arguments.
  • Registration replaces the current inline mechanism: registerPrompts iterates the embedded directory instead of hardcoded definitions. Existing EnabledPrompts config gating applies unchanged (nil/empty -> all published).
  • write_safe_select moves to content/prompts/write_safe_select.md with identical name, description and body, so no observable change for existing clients.

Resources

  • Each file under content/resources/ defines one resource. Frontmatter carries name, description and optional uri (default stackql://docs/<filename-without-extension>), mimeType defaults to text/markdown.
  • Served via resources/list and resources/read. The resources capability is only declared in initialize when at least one resource is present and enabled.
  • Config addition: enabled_resources (list, same semantics as enabled_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/*.md concatenated and published as instructions in the initialize result, suppressible via config
  • content/prompts/*.md published via prompts/list / prompts/get with argument substitution, gated by EnabledPrompts
  • content/resources/*.md published via resources/list / resources/read, capability declared only when non-empty, gated by enabled_resources
  • write_safe_select migrated to content/prompts/write_safe_select.md; prompts/list and prompts/get output 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/list output identical before and after)
  • Binary size delta noted in the PR (expected negligible for markdown content)

Verification

  • MCP Inspector against the stdio binary: confirm instructions in initialize, 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_prompts continue to see filtered sets

Activity

  1. self-assigned this
    on Jul 22, 2026
  2. jeffreyaven commented on Jul 31, 2026

    @jeffreyaven
    MemberAuthor

    closed with #697

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Metadata

Metadata

Assignees

Labels

enhancementNew feature or request

Type

No type

Projects

No projects

    Milestone

    No milestone

    Relationships

    None yet

    Development

    No branches or pull requests

    Issue actions