第 58 章：MCP 原语的三位一体

interface MCPResource {
  uri: string;           // 如 "file:///project/src/index.ts"
  name: string;          // 人类可读名称
  description?: string;   // 描述
  mimeType?: string;      // MIME 类型
  annotations?: {
    audience?: ("user" | "assistant")[];
    priority?: number;     // 0.0-1.0, 越高越重要
    lastModified?: string; // ISO 8601
  };
}

// → src/my-agent/mcp/resource-server.ts
interface ResourceHandler {
  read(uri: string): Promise<ResourceContent>;
  list?(): Promise<MCPResource[]>;
  subscribe?(uri: string): () => void;  // 返回取消订阅函数
}

export class ResourceRegistry {
  private resources = new Map<string, MCPResource>();
  private handlers = new Map<string, ResourceHandler>();

  register(pattern: string, resources: MCPResource[], handler: ResourceHandler): void {
    for (const res of resources) {
      this.resources.set(res.uri, res);
    }
    this.handlers.set(pattern, handler);
  }

  async handleList(cursor?: string): Promise<ListResourcesResult> {
    const all = Array.from(this.resources.values());
    // 简化：不分页
    return { resources: all };
  }

  async handleRead(uri: string): Promise<ReadResourceResult> {
    const resource = this.resources.get(uri);
    if (!resource) throw new Error(`Resource not found: ${uri}`);

    // 找到匹配的 handler
    for (const [pattern, handler] of this.handlers) {
      if (uri.startsWith(pattern)) {
        const content = await handler.read(uri);
        return { contents: [{ uri, mimeType: resource.mimeType, ...content }] };
      }
    }
    throw new Error(`No handler for: ${uri}`);
  }
}

// 文本资源
interface TextResourceContents {
  uri: string;
  mimeType?: string;
  text: string;
}

// 二进制资源
interface BlobResourceContents {
  uri: string;
  mimeType?: string;
  blob: string;  // base64 编码
}

// → src/my-agent/mcp/resource-templates.ts
// 注册模板
server.registerTemplate({
  uriTemplate: "file:///{path}",
  name: "Project Files",
  description: "Read files from the project",
  mimeType: "text/plain",
});

// Client 展开: file:///{path} + { path: "src/index.ts" } → file:///src/index.ts

// Server 声明支持订阅
capabilities: {
  resources: { subscribe: true, listChanged: true }
}

// Server 推送资源更新
{ jsonrpc: "2.0", method: "notifications/resources/updated", params: { uri: "file:///..." } }

interface MCPPrompt {
  name: string;              // "code-review"
  description?: string;      // "Review code for issues"
  arguments?: PromptArgument[];  // 可参数化
}

interface PromptArgument {
  name: string;
  description?: string;
  required?: boolean;
}

// → src/my-agent/mcp/prompt-server.ts
export class PromptRegistry {
  private prompts = new Map<string, {
    definition: MCPPrompt;
    handler: (args: Record<string, string>) => Promise<PromptMessage[]>;
  }>();

  register(
    definition: MCPPrompt,
    handler: (args: Record<string, string>) => Promise<PromptMessage[]>
  ): void {
    this.prompts.set(definition.name, { definition, handler });
  }

  async handleList(): Promise<ListPromptsResult> {
    return {
      prompts: Array.from(this.prompts.values()).map(p => p.definition),
    };
  }

  async handleGet(name: string, args: Record<string, string>): Promise<GetPromptResult> {
    const prompt = this.prompts.get(name);
    if (!prompt) throw new Error(`Prompt not found: ${name}`);

    const messages = await prompt.handler(args);
    return { messages };
  }
}

// 示例 Prompt
registry.register(
  {
    name: "code-review",
    description: "Review code for bugs and style issues",
    arguments: [{ name: "language", description: "Programming language", required: true }],
  },
  async (args) => [{
    role: "user",
    content: {
      type: "text",
      text: `Please review the following ${args.language} code for bugs, security issues, and style problems.`,
    },
  }]
);

// → src/my-agent/mcp/full-server.ts
export class FullMcpServer extends McpServer {
  resources = new ResourceRegistry();
  prompts = new PromptRegistry();
  resourceTemplates: ResourceTemplate[] = [];

  protected async handleMethod(msg: JsonRpcMessage): Promise<void> {
    switch (msg.method) {
      // === Resources ===
      case "resources/list":
        return this.respond(msg.id, await this.resources.handleList(msg.params?.cursor));
      case "resources/read":
        return this.respond(msg.id, await this.resources.handleRead(msg.params.uri));
      case "resources/templates/list":
        return this.respond(msg.id, { resourceTemplates: this.resourceTemplates });

      // === Prompts ===
      case "prompts/list":
        return this.respond(msg.id, await this.prompts.handleList());
      case "prompts/get":
        return this.respond(msg.id, await this.prompts.handleGet(
          msg.params.name, msg.params.arguments
        ));

      // === Tools（继承自 McpServer）===
      default:
        super.handleMethod(msg);
    }
  }
}