TypeScriptでカスタムMCPサーバーとクライアントを構築する：ツール、リソース、プロンプトアーキテクチャ

// src/server.ts
import {
  createMCPSSEServer,
  MCPTool,
  MCPResource,
  MCPContext,
  MCPError,
  MCPErrorCode,
} from '@modelcontextprotocol/sdk';
import express from 'express';
import bodyParser from 'body-parser';
import cors from 'cors';
import { z } from 'zod'; // For schema validation

// --- 1. Define Tool Handlers ---
// Tools are functions the LLM can call. They must have a schema for arguments.

// Tool: `searchWeb`
const searchWebArgsSchema = z.object({
  query: z.string().describe('The search query to execute.'),
  numResults: z.number().int().min(1).max(10).optional().default(3).describe('Number of search results to return.'),
});

const searchWebTool: MCPTool<typeof searchWebArgsSchema> = {
  name: 'searchWeb',
  description: 'Performs a web search and returns relevant results.',
  argsSchema: searchWebArgsSchema,
  handler: async (args, context: MCPContext) => {
    console.log(`[Tool] searchWeb called with query: "${args.query}", results: ${args.numResults}`);
    // In a real scenario, this would call an external search API.
    // For demonstration, we return mock data.
    const mockResults = [
      { title: `Result 1 for "${args.query}"`, url: `https://example.com/search/${args.query}/1` },
      { title: `Result 2 for "${args.query}"`, url: `https://example.com/search/${args.query}/2` },
      { title: `Result 3 for "${args.query}"`, url: `https://example.com/search/${args.query}/3` },
    ];
    return mockResults.slice(0, args.numResults);
  },
};

// Tool: `createFile`
const createFileArgsSchema = z.object({
  path: z.string().describe('The full path including filename where the file should be created.'),
  content: z.string().describe('The content to write into the file.'),
  overwrite: z.boolean().optional().default(false).describe('Whether to overwrite the file if it already exists.'),
});

const createFileTool: MCPTool<typeof createFileArgsSchema> = {
  name: 'createFile',
  description: 'Creates a new file with specified content at a given path.',
  argsSchema: createFileArgsSchema,
  handler: async (args, context: MCPContext) => {
    console.log(`[Tool] createFile called: ${args.path}, overwrite: ${args.overwrite}`);
    // Simulate file system interaction. In production, use `fs.promises`.
    if (!args.overwrite && args.path.includes('existing-file.txt')) { // Mock existing file
      throw new MCPError(MCPErrorCode.RESOURCE_CONFLICT, `File already exists at ${args.path}. Set overwrite to true.`);
    }
    return { success: true, message: `File '${args.path}' created/updated.` };
  },
};

// --- 2. Define Dynamic Resources ---
// Resources provide structured data or schemas that the LLM can query.

// Resource: `projectFiles`
const projectFilesResource: MCPResource = {
  name: 'projectFiles',
  description: 'Lists files and directories within the current project context.',
  schema: {
    type: 'array',
    items: {
      type: 'object',
      properties: {
        name: { type: 'string', description: 'Name of the file or directory.' },
        type: { type: 'string', enum: ['file', 'directory'], description: 'Type of the entry.' },
        size: { type: 'number', description: 'Size in bytes (for files).' },
        lastModified: { type: 'string', format: 'date-time', description: 'Last modification timestamp.' },
      },
      required: ['name', 'type'],
    },
  },
  // The `get` method is called when the LLM requests this resource.
  get: async (context: MCPContext) => {
    console.log('[Resource] projectFiles requested.');
    // In a real application, this would scan the project directory.
    return [
      { name: 'src/', type: 'directory', lastModified: new Date().toISOString() },
      { name: 'src/server.ts', type: 'file', size: 4096, lastModified: new Date().toISOString() },
      { name: 'package.json', type: 'file', size: 1024, lastModified: new Date().toISOString() },
      { name: 'README.md', type: 'file', size: 2048, lastModified: new Date().toISOString() },
    ];
  },
};

// --- 3. Initialize MCP SSE Server ---
const app = express();
app.use(cors()); // Enable CORS for web clients
app.use(bodyParser.json()); // Parse JSON request bodies

const mcpServer = createMCPSSEServer({
  tools: [searchWebTool, createFileTool],
  resources: [projectFilesResource],
  // Optional: Implement an authentication/authorization middleware
  // This example uses a simple token check.
  authenticate: async (token: string | undefined) => {
    if (token === 'my-secret-api-key') {
      return { userId: 'dev-user', roles: ['admin'] }; // Return user context
    }
    throw new MCPError(MCPErrorCode.UNAUTHENTICATED, 'Invalid or missing authentication token.');
  },
  // Optional: Custom error handler for tool/resource execution
  onError: (error: Error) => {
    console.error('MCP Server Error:', error);
    // You might want to log this to a monitoring system.
  },
});

// Mount the MCP server routes
app.use('/mcp', mcpServer.router);

const PORT = process.env.PORT || 3000;
app.listen(PORT, () => {
  console.log(`MCP SSE Server listening on http://localhost:${PORT}/mcp`);
  console.log(`Tools available: ${mcpServer.getToolNames().join(', ')}`);
  console.log(`Resources available: ${mcpServer.getResourceNames().join(', ')}`);
});

// To run this:
// 1. npm init -y
// 2. npm install @modelcontextprotocol/sdk express body-parser cors zod
// 3. ts-node src/server.ts (or compile and run with node)

// Example tool handler structure
const myTool: MCPTool<typeof myArgsSchema> = {
  name: 'myTool',
  description: 'Does something useful.',
  argsSchema: myArgsSchema,
  handler: async (args, context) => {
    // `args` is type-safe due to `myArgsSchema`
    // `context` contains information about the current MCP session (e.g., authentication)
    console.log('Tool called with:', args);
    // Perform operations, e.g., API calls, file system access
    return { status: 'success', data: 'some result' };
  },
};

// Example resource structure
const myResource: MCPResource = {
  name: 'myResource',
  description: 'Provides dynamic data.',
  schema: {
    type: 'object',
    properties: {
      id: { type: 'string' },
      value: { type: 'number' },
    },
    required: ['id', 'value'],
  },
  get: async (context) => {
    // Fetch or generate dynamic data
    return [{ id: 'item1', value: 123 }, { id: 'item2', value: 456 }];
  },
};

// src/client.ts
import { createMCPClient, MCPClientOptions } from '@modelcontextprotocol/sdk';

async function runMCPClient() {
  const clientOptions: MCPClientOptions = {
    // For SSE, specify the base URL of your MCP server
    // For Stdio, you'd pass `process.stdin` and `process.stdout`
    transport: {
      type: 'sse',
      baseUrl: 'http://localhost:3000/mcp',
      headers: {
        'Authorization': 'Bearer my-secret-api-key', // Include authentication token
      },
    },
    // Optional: Logger for debugging
    logger: console,
  };

  const client = createMCPClient(clientOptions);

  try {
    // --- 1. Get available tools and resources ---
    const tools = await client.getTools();
    console.log('Available Tools:', tools.map(t => t.name));

    const resources = await client.getResources();
    console.log('Available Resources:', resources.map(r => r.name));

    // --- 2. Call a tool ---
    console.log('\nCalling searchWeb tool...');
    const searchResults = await client.callTool('searchWeb', { query: 'MCP protocol best practices', numResults: 2 });
    console.log('Search Results:', searchResults);

    // --- 3. Get a resource ---
    console.log('\nGetting projectFiles resource...');
    const projectFiles = await client.getResource('projectFiles');
    console.log('Project Files:', projectFiles);

    // --- 4. Handle errors ---
    console.log('\nCalling createFile tool with conflict...');
    try {
      await client.callTool('createFile', { path: 'existing-file.txt', content: 'new content' });
    } catch (error: any) {
      console.error('Error calling createFile:', error.message);
    }

    console.log('\nCalling createFile tool with overwrite...');
    const createResult = await client.callTool('createFile', { path: 'new-file.txt', content: 'Hello, MCP!', overwrite: true });
    console.log('Create File Result:', createResult);

  } catch (error) {
    console.error('MCP Client Error:', error);
  }
}

runMCPClient();

// To run this:
// 1. Ensure the server (src/server.ts) is running.
// 2. npm install @modelcontextprotocol/sdk
// 3. ts-node src/client.ts

You are an AI assistant with access to the following tools and resources:

<tools>
{{#each tools}}
<tool_code>
{
  "name": "{{this.name}}",
  "description": "{{this.description}}",
  "parameters": {{json this.argsSchema}}
}
</tool_code>
{{/each}}
</tools>

<resources>
{{#each resources}}
<resource_code>
{
  "name": "{{this.name}}",
  "description": "{{this.description}}",
  "schema": {{json this.schema}}
}
</resource_code>
{{/each}}
</resources>

<context>
{{#if currentResourceData}}
<resource_data name="{{currentResourceData.name}}">
{{json currentResourceData.data}}
</resource_data>
{{/if}}
</context>

Your goal is to assist the user by leveraging these capabilities.
If you need to perform an action, use the `<call_tool>` tag.
If you need to retrieve information, use the `<get_resource>` tag.
If you have retrieved information from a resource, it will appear in the `<context>` block.

User: {{user_query}}