Add Instructions Support to FastMcpStarter

[jolestar]

Summary

The FastMcpStarter currently does not expose the instructions parameter, which is a standard field in the MCP (Model Context Protocol) specification. This prevents servers from providing usage instructions to clients, limiting the LLM's ability to understand available tools and resources.

Background

According to the MCP specification, instructions is an optional field in the InitializeResult that describes how to use the server and its features. This information can be used by clients to improve the LLM's understanding of available tools, resources, etc., and is typically added to the system prompt.

From the MCP SDK types:

/**
 * Instructions describing how to use the server and its features.
 * 
 * This can be used by clients to improve the LLM's understanding of available tools, resources, etc. 
 * It can be thought of like a "hint" to the model. For example, this information MAY be added to the system prompt.
 */
instructions: z.ZodOptional<z.ZodString>;

Current Issue

In FastMcpStarter.ts, the FastMCP server is created without the instructions parameter:

const server = new FastMCP({
  name: opts.serviceId || 'nuwa-mcp-server',
  version: '1.0.0',
  // Missing: instructions parameter
});

Similarly, FastMCPSession is created without instructions:

const session = new FastMCPSession({
  name: opts.serviceId || 'nuwa-mcp-server',
  version: '1.0.0',
  // Missing: instructions parameter
  // ... other config
});

How Clients Access Instructions

MCP clients access instructions through the standard initialization handshake:

1. Client calls connect() method (returns Promise<void>)
2. After successful connection, client calls getInstructions() to retrieve server instructions
3. Instructions are automatically included in the InitializeResult during the MCP handshake

// Client usage example
const client = new McpClient({ name: 'my-client', version: '1.0.0' });
await client.connect(transport);
const instructions = client.getInstructions(); // Gets instructions from server

Proposed Solution

1. Add instructions option to FastMcpServerOptions

export interface FastMcpServerOptions extends McpPaymentKitOptions {
  /** Instructions describing how to use the server and its features */
  instructions?: string;
  port?: number;
  endpoint?: `/${string}`;
  register?: (registrar: PaymentMcpToolRegistrar) => void;
  wellKnown?: {
    enabled?: boolean;
    path?: `/${string}`;
  };
}

2. Pass instructions to FastMCP constructor

const server = new FastMCP({
  name: opts.serviceId || 'nuwa-mcp-server',
  version: '1.0.0',
  instructions: opts.instructions, // Add this line
});

3. Pass instructions to FastMCPSession constructor

const session = new FastMCPSession({
  name: opts.serviceId || 'nuwa-mcp-server',
  version: '1.0.0',
  instructions: opts.instructions, // Add this line
  // ... other config
});

4. Update helper functions

Both createFastMcpServer and createFastMcpServerFromEnv should accept and forward the instructions parameter.

Example Usage

After implementation, developers could use it like this:

const server = await createFastMcpServerFromEnv(env, {
  serviceId: "my-service",
  instructions: "This server provides weather data and location services. Use get_weather for current conditions and search_locations to find places.",
  port: 8080,
  // ... other options
});

Benefits

1. Improved LLM Understanding: Instructions help LLMs better understand how to use the server's tools and resources
2. Better User Experience: More context leads to more accurate tool usage and better results
3. MCP Compliance: Follows the standard MCP specification for server metadata
4. Backward Compatibility: Adding optional instructions parameter doesn't break existing code

Files to Modify

• nuwa-kit/typescript/packages/payment-kit/src/transport/mcp/FastMcpStarter.ts
  • Add instructions? to FastMcpServerOptions interface
  • Pass instructions to FastMCP constructor
  • Pass instructions to FastMCPSession constructor
  • Update function signatures as needed

Acceptance Criteria

• FastMcpServerOptions interface includes optional instructions parameter
• Instructions are passed to both FastMCP and FastMCPSession constructors
• createFastMcpServer and createFastMcpServerFromEnv accept instructions parameter
• Existing functionality remains unchanged (backward compatible)
• MCP clients can retrieve instructions via getInstructions() method
• Documentation/examples updated to show instructions usage

Priority

Medium - This is a standard MCP feature that improves the developer experience and LLM interaction quality, but doesn't break existing functionality.