Skip to content

feat(ai): support InitializeResult.instructions on McpServer#6224

Open
richburdon wants to merge 6 commits intoEffect-TS:mainfrom
dxos:claude/xenodochial-jepsen-9dc87a
Open

feat(ai): support InitializeResult.instructions on McpServer#6224
richburdon wants to merge 6 commits intoEffect-TS:mainfrom
dxos:claude/xenodochial-jepsen-9dc87a

Conversation

@richburdon
Copy link
Copy Markdown
Contributor

Summary

Add an optional instructions field to the McpServer layer options
(layer, layerStdio, layerHttp, layerHttpRouter). When provided, the
string is returned in the InitializeResult.instructions field per the
MCP spec.

InitializeResult.instructions is the built-in MCP mechanism for a server
to inject system-prompt-level guidance into the client at session start.
The current @effect/ai API doesn't expose it, forcing downstream users
to either fork or post-process JSON-RPC responses to add it. The schema in
McpSchema.InitializeResult already supports the field — this PR just
plumbs it through the public layer constructors.

The option is purely additive and omitted from the response when not set
(no instructions: undefined is emitted).

Before

McpServer.layerHttp({
  name: "Demo Server",
  version: "1.0.0",
  path: "/mcp"
})

After

McpServer.layerHttp({
  name: "Demo Server",
  version: "1.0.0",
  path: "/mcp",
  instructions: "Always greet the user with a friendly hello."
})

Test plan

  • pnpm check (tsc strict) passes
  • pnpm test passes — added two tests in packages/ai/ai/test/McpServer.test.ts:
    • asserts InitializeResult.instructions === "be helpful" when the option is set
    • asserts the field is absent from the response when the option is omitted
  • Added changeset (@effect/ai minor — additive API)

🤖 Generated with Claude Code

dmaretskyi and others added 5 commits August 1, 2025 12:19
Update OpenAi client to work with "openai-compatible" providers
Add an optional `instructions` field to the `McpServer` layer options
(`layer`, `layerStdio`, `layerHttp`, `layerHttpRouter`). When provided, the
string is returned in the `InitializeResult.instructions` field per the MCP
spec, giving servers a built-in way to inject system-prompt-level guidance
into clients at session start.

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
@richburdon richburdon requested a review from IMax153 as a code owner May 8, 2026 22:53
@github-project-automation github-project-automation Bot moved this to Discussion Ongoing in PR Backlog May 8, 2026
@changeset-bot
Copy link
Copy Markdown

changeset-bot Bot commented May 8, 2026

🦋 Changeset detected

Latest commit: 242c342

The changes in this PR will be included in the next version bump.

This PR includes changesets to release 6 packages
Name Type
@effect/ai Minor
@effect/ai-amazon-bedrock Major
@effect/ai-anthropic Major
@effect/ai-google Major
@effect/ai-openai Major
@effect/ai-openrouter Major

Not sure what this means? Click here to learn what changesets are.

Click here if you're a maintainer who wants to add another changeset to this PR

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

Labels

None yet

Projects

Status: Discussion Ongoing

Development

Successfully merging this pull request may close these issues.

2 participants