@nahisaho/katashiro-mcp-server 0.1.0

package/src/protocol/protocol-handler.ts

@@ -0,0 +1,438 @@
+/**
+ * MCPProtocolHandler - MCP Protocol implementation
+ *
+ * Implements the Model Context Protocol JSON-RPC handlers
+ * Handles lifecycle, tools, resources, and prompts methods
+ *
+ * @module @nahisaho/katashiro-mcp-server
+ * @task TSK-061
+ */
+
+import { isOk } from '@nahisaho/katashiro-core';
+import type {
+  KatashiroMCPServer,
+  ServerCapabilities,
+  ServerInfo,
+  MCPResource,
+} from '../server/mcp-server.js';
+import {
+  type JsonRpcRequest,
+  type JsonRpcResponse,
+  type JsonRpcNotification,
+  JsonRpcErrorCode,
+  createSuccessResponse,
+  createErrorResponse,
+} from '../transport/stdio-transport.js';
+
+/**
+ * MCP Protocol version
+ */
+export const MCP_PROTOCOL_VERSION = '2024-11-05';
+
+/**
+ * Initialize request params
+ */
+export interface InitializeParams {
+  protocolVersion: string;
+  capabilities: Record<string, unknown>;
+  clientInfo: {
+    name: string;
+    version: string;
+  };
+}
+
+/**
+ * Initialize result
+ */
+export interface InitializeResult {
+  protocolVersion: string;
+  capabilities: ServerCapabilities;
+  serverInfo: ServerInfo;
+}
+
+/**
+ * Tools/list result
+ */
+export interface ToolsListResult {
+  tools: Array<{
+    name: string;
+    description: string;
+    inputSchema: unknown;
+  }>;
+}
+
+/**
+ * Tools/call params
+ */
+export interface ToolsCallParams {
+  name: string;
+  arguments?: Record<string, unknown>;
+}
+
+/**
+ * Resources/list result
+ */
+export interface ResourcesListResult {
+  resources: Array<{
+    uri: string;
+    name: string;
+    description?: string;
+    mimeType?: string;
+  }>;
+}
+
+/**
+ * Resources/read params
+ */
+export interface ResourcesReadParams {
+  uri: string;
+}
+
+/**
+ * Prompts/list result
+ */
+export interface PromptsListResult {
+  prompts: Array<{
+    name: string;
+    description: string;
+    arguments?: Array<{
+      name: string;
+      description: string;
+      required?: boolean;
+    }>;
+  }>;
+}
+
+/**
+ * Prompts/get params
+ */
+export interface PromptsGetParams {
+  name: string;
+  arguments?: Record<string, unknown>;
+}
+
+/**
+ * Protocol state
+ */
+export type ProtocolState = 'uninitialized' | 'initializing' | 'ready' | 'shutdown';
+
+/**
+ * MCPProtocolHandler
+ *
+ * Handles MCP protocol messages and delegates to KatashiroMCPServer
+ */
+export class MCPProtocolHandler {
+  private state: ProtocolState = 'uninitialized';
+  private clientInfo: { name: string; version: string } | null = null;
+
+  constructor(private readonly server: KatashiroMCPServer) {}
+
+  /**
+   * Get current protocol state
+   */
+  getState(): ProtocolState {
+    return this.state;
+  }
+
+  /**
+   * Get client info (after initialization)
+   */
+  getClientInfo(): { name: string; version: string } | null {
+    return this.clientInfo;
+  }
+
+  /**
+   * Handle incoming JSON-RPC message
+   */
+  async handleMessage(
+    message: JsonRpcRequest | JsonRpcNotification
+  ): Promise<JsonRpcResponse | void> {
+    const isRequest = 'id' in message;
+    const method = message.method;
+
+    // Handle notifications (no response expected)
+    if (!isRequest) {
+      await this.handleNotification(message as JsonRpcNotification);
+      return;
+    }
+
+    const request = message as JsonRpcRequest;
+
+    // Route based on method
+    try {
+      switch (method) {
+        case 'initialize':
+          return this.handleInitialize(request);
+
+        case 'ping':
+          return this.handlePing(request);
+
+        case 'tools/list':
+          return this.handleToolsList(request);
+
+        case 'tools/call':
+          return this.handleToolsCall(request);
+
+        case 'resources/list':
+          return this.handleResourcesList(request);
+
+        case 'resources/read':
+          return this.handleResourcesRead(request);
+
+        case 'prompts/list':
+          return this.handlePromptsList(request);
+
+        case 'prompts/get':
+          return this.handlePromptsGet(request);
+
+        default:
+          return createErrorResponse(
+            request.id,
+            JsonRpcErrorCode.MethodNotFound,
+            `Method not found: ${method}`
+          );
+      }
+    } catch (error) {
+      return createErrorResponse(
+        request.id,
+        JsonRpcErrorCode.InternalError,
+        error instanceof Error ? error.message : 'Internal error'
+      );
+    }
+  }
+
+  /**
+   * Handle notifications
+   */
+  private async handleNotification(
+    notification: JsonRpcNotification
+  ): Promise<void> {
+    switch (notification.method) {
+      case 'notifications/initialized':
+        if (this.state === 'initializing') {
+          this.state = 'ready';
+        }
+        break;
+
+      case 'notifications/cancelled':
+        // Handle cancellation (not implemented yet)
+        break;
+
+      default:
+        // Unknown notification - ignore
+        break;
+    }
+  }
+
+  /**
+   * Handle initialize request
+   */
+  private handleInitialize(request: JsonRpcRequest): JsonRpcResponse {
+    if (this.state !== 'uninitialized') {
+      return createErrorResponse(
+        request.id,
+        JsonRpcErrorCode.InvalidRequest,
+        'Already initialized'
+      );
+    }
+
+    const params = request.params as InitializeParams;
+    this.clientInfo = params.clientInfo;
+    this.state = 'initializing';
+
+    const result: InitializeResult = {
+      protocolVersion: MCP_PROTOCOL_VERSION,
+      capabilities: this.server.getCapabilities(),
+      serverInfo: this.server.getServerInfo(),
+    };
+
+    return createSuccessResponse(request.id, result);
+  }
+
+  /**
+   * Handle ping request
+   */
+  private handlePing(request: JsonRpcRequest): JsonRpcResponse {
+    return createSuccessResponse(request.id, {});
+  }
+
+  /**
+   * Handle tools/list request
+   */
+  private handleToolsList(request: JsonRpcRequest): JsonRpcResponse {
+    this.ensureReady();
+
+    const tools = this.server.getTools();
+    const toolsResult: ToolsListResult = {
+      tools: tools.map((tool) => ({
+        name: tool.name,
+        description: tool.description,
+        inputSchema: tool.inputSchema,
+      })),
+    };
+
+    return createSuccessResponse(request.id, toolsResult);
+  }
+
+  /**
+   * Handle tools/call request
+   */
+  private async handleToolsCall(
+    request: JsonRpcRequest
+  ): Promise<JsonRpcResponse> {
+    this.ensureReady();
+
+    const params = request.params as ToolsCallParams;
+    if (!params.name) {
+      return createErrorResponse(
+        request.id,
+        JsonRpcErrorCode.InvalidParams,
+        'Tool name required'
+      );
+    }
+
+    const result = await this.server.executeTool(
+      params.name,
+      params.arguments || {}
+    );
+
+    if (isOk(result)) {
+      return createSuccessResponse(request.id, result.value);
+    } else {
+      return createErrorResponse(
+        request.id,
+        JsonRpcErrorCode.InternalError,
+        result.error.message
+      );
+    }
+  }
+
+  /**
+   * Handle resources/list request
+   */
+  private async handleResourcesList(
+    request: JsonRpcRequest
+  ): Promise<JsonRpcResponse> {
+    this.ensureReady();
+
+    const result = await this.server.listResources();
+
+    if (isOk(result)) {
+      const resources: ResourcesListResult = {
+        resources: result.value.map((r: MCPResource) => ({
+          uri: r.uri,
+          name: r.name,
+          description: r.description,
+          mimeType: r.mimeType,
+        })),
+      };
+      return createSuccessResponse(request.id, resources);
+    } else {
+      return createErrorResponse(
+        request.id,
+        JsonRpcErrorCode.InternalError,
+        result.error.message
+      );
+    }
+  }
+
+  /**
+   * Handle resources/read request
+   */
+  private async handleResourcesRead(
+    request: JsonRpcRequest
+  ): Promise<JsonRpcResponse> {
+    this.ensureReady();
+
+    const params = request.params as ResourcesReadParams;
+    if (!params.uri) {
+      return createErrorResponse(
+        request.id,
+        JsonRpcErrorCode.InvalidParams,
+        'Resource URI required'
+      );
+    }
+
+    const result = await this.server.readResource(params.uri);
+
+    if (isOk(result)) {
+      return createSuccessResponse(request.id, {
+        contents: [
+          {
+            uri: params.uri,
+            mimeType: 'text/plain',
+            text: result.value,
+          },
+        ],
+      });
+    } else {
+      return createErrorResponse(
+        request.id,
+        JsonRpcErrorCode.InternalError,
+        result.error.message
+      );
+    }
+  }
+
+  /**
+   * Handle prompts/list request
+   */
+  private handlePromptsList(request: JsonRpcRequest): JsonRpcResponse {
+    this.ensureReady();
+
+    const prompts = this.server.getPrompts();
+    const promptsResult: PromptsListResult = {
+      prompts: prompts.map((prompt) => ({
+        name: prompt.name,
+        description: prompt.description,
+        arguments: prompt.arguments,
+      })),
+    };
+
+    return createSuccessResponse(request.id, promptsResult);
+  }
+
+  /**
+   * Handle prompts/get request
+   */
+  private async handlePromptsGet(
+    request: JsonRpcRequest
+  ): Promise<JsonRpcResponse> {
+    this.ensureReady();
+
+    const params = request.params as PromptsGetParams;
+    if (!params.name) {
+      return createErrorResponse(
+        request.id,
+        JsonRpcErrorCode.InvalidParams,
+        'Prompt name required'
+      );
+    }
+
+    const result = await this.server.executePrompt(
+      params.name,
+      params.arguments || {}
+    );
+
+    if (isOk(result)) {
+      return createSuccessResponse(request.id, result.value);
+    } else {
+      return createErrorResponse(
+        request.id,
+        JsonRpcErrorCode.InternalError,
+        result.error.message
+      );
+    }
+  }
+
+  /**
+   * Ensure server is ready for operations
+   */
+  private ensureReady(): void {
+    // Allow operations in both initializing and ready states
+    // This matches MCP spec where operations can happen after initialize
+    if (this.state === 'uninitialized') {
+      throw new Error('Server not initialized');
+    }
+  }
+}

package/src/resources/resource-manager.ts

@@ -0,0 +1,265 @@
+/**
+ * ResourceManager - リソース管理
+ *
+ * MCPリソースの登録・読み取り・購読を管理
+ *
+ * @module @nahisaho/katashiro-mcp-server
+ * @task TSK-063
+ */
+
+import { ok, err, type Result } from '@nahisaho/katashiro-core';
+
+/**
+ * Resource content
+ */
+export interface ResourceContent {
+  content: string;
+  mimeType?: string;
+}
+
+/**
+ * Content provider function
+ */
+export type ContentProvider = () => Promise<ResourceContent>;
+
+/**
+ * Resource definition
+ */
+export interface ResourceDefinition {
+  uri: string;
+  name: string;
+  description?: string;
+  mimeType?: string;
+  content?: string;
+  provider?: ContentProvider;
+}
+
+/**
+ * Resource template
+ */
+export interface ResourceTemplate {
+  uriTemplate: string;
+  name: string;
+  description?: string;
+  mimeType?: string;
+}
+
+/**
+ * Subscription callback
+ */
+export type SubscriptionCallback = (uri: string, content: string) => void;
+
+/**
+ * List options
+ */
+export interface ListOptions {
+  prefix?: string;
+}
+
+/**
+ * ResourceManager
+ *
+ * Manages MCP resources and subscriptions
+ */
+export class ResourceManager {
+  private resources: Map<string, ResourceDefinition> = new Map();
+  private subscriptions: Map<string, Map<string, SubscriptionCallback>> = new Map();
+  private subscriptionCounter = 0;
+
+  /**
+   * Register a resource
+   *
+   * @param resource - Resource to register
+   * @returns Result
+   */
+  register(resource: ResourceDefinition): Result<void, Error> {
+    try {
+      if (this.resources.has(resource.uri)) {
+        return err(new Error(`Resource already registered: ${resource.uri}`));
+      }
+      this.resources.set(resource.uri, resource);
+      return ok(undefined);
+    } catch (error) {
+      return err(error instanceof Error ? error : new Error(String(error)));
+    }
+  }
+
+  /**
+   * List all resources
+   *
+   * @param options - List options
+   * @returns Array of resources
+   */
+  list(options: ListOptions = {}): Result<ResourceDefinition[], Error> {
+    try {
+      let resources = Array.from(this.resources.values());
+
+      if (options.prefix) {
+        resources = resources.filter((r) => r.uri.startsWith(options.prefix!));
+      }
+
+      return ok(resources);
+    } catch (error) {
+      return err(error instanceof Error ? error : new Error(String(error)));
+    }
+  }
+
+  /**
+   * Read a resource
+   *
+   * @param uri - Resource URI
+   * @returns Resource content
+   */
+  async read(uri: string): Promise<Result<ResourceContent, Error>> {
+    try {
+      const resource = this.resources.get(uri);
+      if (!resource) {
+        return err(new Error(`Resource not found: ${uri}`));
+      }
+
+      // Use provider if available
+      if (resource.provider) {
+        const content = await resource.provider();
+        return ok(content);
+      }
+
+      // Return static content
+      return ok({
+        content: resource.content ?? '',
+        mimeType: resource.mimeType,
+      });
+    } catch (error) {
+      return err(error instanceof Error ? error : new Error(String(error)));
+    }
+  }
+
+  /**
+   * Subscribe to resource changes
+   *
+   * @param uri - Resource URI
+   * @param callback - Callback function
+   * @returns Subscription ID
+   */
+  subscribe(uri: string, callback: SubscriptionCallback): Result<string, Error> {
+    try {
+      if (!this.resources.has(uri)) {
+        return err(new Error(`Resource not found: ${uri}`));
+      }
+
+      if (!this.subscriptions.has(uri)) {
+        this.subscriptions.set(uri, new Map());
+      }
+
+      const subId = `sub-${++this.subscriptionCounter}`;
+      this.subscriptions.get(uri)!.set(subId, callback);
+
+      return ok(subId);
+    } catch (error) {
+      return err(error instanceof Error ? error : new Error(String(error)));
+    }
+  }
+
+  /**
+   * Unsubscribe from resource changes
+   *
+   * @param subscriptionId - Subscription ID
+   * @returns Whether unsubscribed
+   */
+  unsubscribe(subscriptionId: string): Result<boolean, Error> {
+    try {
+      for (const subs of this.subscriptions.values()) {
+        if (subs.has(subscriptionId)) {
+          subs.delete(subscriptionId);
+          return ok(true);
+        }
+      }
+      return ok(false);
+    } catch (error) {
+      return err(error instanceof Error ? error : new Error(String(error)));
+    }
+  }
+
+  /**
+   * Update resource content and notify subscribers
+   *
+   * @param uri - Resource URI
+   * @param content - New content
+   * @returns Result
+   */
+  async update(uri: string, content: string): Promise<Result<void, Error>> {
+    try {
+      const resource = this.resources.get(uri);
+      if (!resource) {
+        return err(new Error(`Resource not found: ${uri}`));
+      }
+
+      // Update content
+      resource.content = content;
+      this.resources.set(uri, resource);
+
+      // Notify subscribers
+      const subs = this.subscriptions.get(uri);
+      if (subs) {
+        for (const callback of subs.values()) {
+          callback(uri, content);
+        }
+      }
+
+      return ok(undefined);
+    } catch (error) {
+      return err(error instanceof Error ? error : new Error(String(error)));
+    }
+  }
+
+  /**
+   * List resource templates
+   *
+   * @returns Array of templates
+   */
+  listTemplates(): Result<ResourceTemplate[], Error> {
+    try {
+      // Built-in templates
+      const templates: ResourceTemplate[] = [
+        {
+          uriTemplate: 'katashiro://knowledge/{topic}',
+          name: 'Knowledge Topic',
+          description: 'Access knowledge graph by topic',
+          mimeType: 'application/json',
+        },
+        {
+          uriTemplate: 'katashiro://patterns/{type}',
+          name: 'Pattern Type',
+          description: 'Access patterns by type',
+          mimeType: 'application/json',
+        },
+      ];
+
+      return ok(templates);
+    } catch (error) {
+      return err(error instanceof Error ? error : new Error(String(error)));
+    }
+  }
+
+  /**
+   * Unregister a resource
+   *
+   * @param uri - Resource URI
+   * @returns Whether unregistered
+   */
+  unregister(uri: string): Result<boolean, Error> {
+    try {
+      this.subscriptions.delete(uri);
+      return ok(this.resources.delete(uri));
+    } catch (error) {
+      return err(error instanceof Error ? error : new Error(String(error)));
+    }
+  }
+
+  /**
+   * Clear all resources
+   */
+  clear(): void {
+    this.resources.clear();
+    this.subscriptions.clear();
+  }
+}