@nahisaho/katashiro-mcp-server 0.1.0

package/src/transport/stdio-transport.ts

@@ -0,0 +1,272 @@
+/**
+ * StdioTransport - STDIO based JSON-RPC transport for MCP
+ *
+ * MCP specification compliant transport layer
+ * Uses newline-delimited JSON (NDJSON) for message framing
+ *
+ * @module @nahisaho/katashiro-mcp-server
+ * @task TSK-061
+ */
+
+import * as readline from 'readline';
+import type { Readable, Writable } from 'stream';
+
+/**
+ * JSON-RPC 2.0 Request
+ */
+export interface JsonRpcRequest {
+  jsonrpc: '2.0';
+  id: string | number;
+  method: string;
+  params?: unknown;
+}
+
+/**
+ * JSON-RPC 2.0 Notification (no id)
+ */
+export interface JsonRpcNotification {
+  jsonrpc: '2.0';
+  method: string;
+  params?: unknown;
+}
+
+/**
+ * JSON-RPC 2.0 Response
+ */
+export interface JsonRpcResponse {
+  jsonrpc: '2.0';
+  id: string | number;
+  result?: unknown;
+  error?: JsonRpcError;
+}
+
+/**
+ * JSON-RPC 2.0 Error
+ */
+export interface JsonRpcError {
+  code: number;
+  message: string;
+  data?: unknown;
+}
+
+/**
+ * Standard JSON-RPC error codes
+ */
+export const JsonRpcErrorCode = {
+  ParseError: -32700,
+  InvalidRequest: -32600,
+  MethodNotFound: -32601,
+  InvalidParams: -32602,
+  InternalError: -32603,
+} as const;
+
+/**
+ * Message handler type
+ */
+export type MessageHandler = (
+  message: JsonRpcRequest | JsonRpcNotification
+) => Promise<JsonRpcResponse | void>;
+
+/**
+ * Transport state
+ */
+export type TransportState = 'disconnected' | 'connected' | 'closed';
+
+/**
+ * StdioTransport
+ *
+ * Handles STDIO communication for MCP servers
+ * Implements JSON-RPC 2.0 over newline-delimited JSON
+ */
+export class StdioTransport {
+  private state: TransportState = 'disconnected';
+  private readline: readline.Interface | null = null;
+  private messageHandler: MessageHandler | null = null;
+  private errorHandler: ((error: Error) => void) | null = null;
+
+  constructor(
+    private readonly input: Readable = process.stdin,
+    private readonly output: Writable = process.stdout
+  ) {}
+
+  /**
+   * Get current state
+   */
+  getState(): TransportState {
+    return this.state;
+  }
+
+  /**
+   * Set message handler
+   */
+  onMessage(handler: MessageHandler): void {
+    this.messageHandler = handler;
+  }
+
+  /**
+   * Set error handler
+   */
+  onError(handler: (error: Error) => void): void {
+    this.errorHandler = handler;
+  }
+
+  /**
+   * Start the transport
+   */
+  start(): void {
+    if (this.state !== 'disconnected') {
+      return;
+    }
+
+    this.readline = readline.createInterface({
+      input: this.input,
+      terminal: false,
+    });
+
+    this.readline.on('line', (line) => {
+      this.handleLine(line);
+    });
+
+    this.readline.on('close', () => {
+      this.state = 'closed';
+    });
+
+    this.readline.on('error', (error) => {
+      if (this.errorHandler) {
+        this.errorHandler(error);
+      }
+    });
+
+    this.state = 'connected';
+  }
+
+  /**
+   * Stop the transport
+   */
+  stop(): void {
+    if (this.readline) {
+      this.readline.close();
+      this.readline = null;
+    }
+    this.state = 'closed';
+  }
+
+  /**
+   * Send a response
+   */
+  send(message: JsonRpcResponse | JsonRpcNotification): void {
+    if (this.state !== 'connected') {
+      throw new Error('Transport not connected');
+    }
+
+    const json = JSON.stringify(message);
+    this.output.write(json + '\n');
+  }
+
+  /**
+   * Handle incoming line
+   */
+  private async handleLine(line: string): Promise<void> {
+    if (!line.trim()) {
+      return;
+    }
+
+    try {
+      const message = JSON.parse(line) as JsonRpcRequest | JsonRpcNotification;
+
+      // Validate JSON-RPC message
+      if (!this.isValidJsonRpcMessage(message)) {
+        this.sendError(null, JsonRpcErrorCode.InvalidRequest, 'Invalid Request');
+        return;
+      }
+
+      if (this.messageHandler) {
+        const response = await this.messageHandler(message);
+        if (response) {
+          this.send(response);
+        }
+      }
+    } catch (error) {
+      // Parse error
+      this.sendError(null, JsonRpcErrorCode.ParseError, 'Parse error');
+    }
+  }
+
+  /**
+   * Validate JSON-RPC message
+   */
+  private isValidJsonRpcMessage(
+    message: unknown
+  ): message is JsonRpcRequest | JsonRpcNotification {
+    if (typeof message !== 'object' || message === null) {
+      return false;
+    }
+
+    const msg = message as Record<string, unknown>;
+    if (msg['jsonrpc'] !== '2.0') {
+      return false;
+    }
+
+    if (typeof msg['method'] !== 'string') {
+      return false;
+    }
+
+    return true;
+  }
+
+  /**
+   * Send error response
+   */
+  private sendError(
+    id: string | number | null,
+    code: number,
+    message: string,
+    data?: unknown
+  ): void {
+    const response: JsonRpcResponse = {
+      jsonrpc: '2.0',
+      id: id ?? 0,
+      error: {
+        code,
+        message,
+        data,
+      },
+    };
+
+    this.send(response);
+  }
+}
+
+/**
+ * Create a success response
+ */
+export function createSuccessResponse(
+  id: string | number,
+  result: unknown
+): JsonRpcResponse {
+  return {
+    jsonrpc: '2.0',
+    id,
+    result,
+  };
+}
+
+/**
+ * Create an error response
+ */
+export function createErrorResponse(
+  id: string | number,
+  code: number,
+  message: string,
+  data?: unknown
+): JsonRpcResponse {
+  return {
+    jsonrpc: '2.0',
+    id,
+    error: {
+      code,
+      message,
+      data,
+    },
+  };
+}

package/tests/unit/mcp-server.test.ts

@@ -0,0 +1,164 @@
+/**
+ * MCP Server テスト
+ *
+ * @task TSK-060
+ */
+
+import { describe, it, expect, beforeEach } from 'vitest';
+import { KatashiroMCPServer } from '../../src/server/mcp-server.js';
+import { isOk } from '@nahisaho/katashiro-core';
+
+describe('KatashiroMCPServer', () => {
+  let server: KatashiroMCPServer;
+
+  beforeEach(() => {
+    server = new KatashiroMCPServer();
+  });
+
+  describe('initialization', () => {
+    it('should initialize with default config', () => {
+      expect(server).toBeDefined();
+      expect(server.getName()).toBe('katashiro');
+    });
+
+    it('should have server info', () => {
+      const info = server.getServerInfo();
+      expect(info.name).toBe('katashiro');
+      expect(info.version).toBe('0.1.0');
+    });
+
+    it('should have capabilities', () => {
+      const caps = server.getCapabilities();
+      expect(caps.tools).toBeDefined();
+      expect(caps.resources).toBeDefined();
+      expect(caps.prompts).toBeDefined();
+    });
+
+    it('should have all tools registered', () => {
+      const tools = server.getTools();
+      expect(tools.length).toBeGreaterThan(0);
+
+      const toolNames = tools.map((t) => t.name);
+      expect(toolNames).toContain('web_search');
+      expect(toolNames).toContain('analyze_content');
+      expect(toolNames).toContain('generate_summary');
+      expect(toolNames).toContain('query_knowledge');
+      expect(toolNames).toContain('generate_report');
+    });
+
+    it('should have all prompts registered', () => {
+      const prompts = server.getPrompts();
+      expect(prompts.length).toBeGreaterThan(0);
+
+      const promptNames = prompts.map((p) => p.name);
+      expect(promptNames).toContain('research_topic');
+      expect(promptNames).toContain('analyze_document');
+      expect(promptNames).toContain('create_presentation');
+    });
+  });
+
+  describe('tool execution', () => {
+    it('should execute web_search tool', async () => {
+      const result = await server.executeTool('web_search', {
+        query: 'TypeScript best practices',
+      });
+
+      expect(isOk(result)).toBe(true);
+      if (isOk(result)) {
+        expect(result.value.content).toBeDefined();
+        expect(result.value.content[0].type).toBe('text');
+      }
+    });
+
+    it('should execute analyze_content tool', async () => {
+      const result = await server.executeTool('analyze_content', {
+        content: 'This is a sample text for analysis.',
+        type: 'text',
+      });
+
+      expect(isOk(result)).toBe(true);
+      if (isOk(result)) {
+        expect(result.value.content).toBeDefined();
+      }
+    });
+
+    it('should execute generate_summary tool', async () => {
+      const result = await server.executeTool('generate_summary', {
+        content: 'Long article about AI developments in 2025...',
+        style: 'brief',
+      });
+
+      expect(isOk(result)).toBe(true);
+    });
+
+    it('should execute query_knowledge tool', async () => {
+      const result = await server.executeTool('query_knowledge', {
+        query: 'AI research',
+      });
+
+      expect(isOk(result)).toBe(true);
+    });
+
+    it('should execute generate_report tool', async () => {
+      const result = await server.executeTool('generate_report', {
+        topic: 'Market Analysis',
+        format: 'markdown',
+      });
+
+      expect(isOk(result)).toBe(true);
+    });
+
+    it('should return error for unknown tool', async () => {
+      const result = await server.executeTool('unknown_tool', {});
+      expect(isOk(result)).toBe(false);
+    });
+  });
+
+  describe('prompt execution', () => {
+    it('should execute research_topic prompt', async () => {
+      const result = await server.executePrompt('research_topic', {
+        topic: 'Machine Learning',
+      });
+
+      expect(isOk(result)).toBe(true);
+      if (isOk(result)) {
+        expect(result.value.messages).toBeDefined();
+        expect(result.value.messages.length).toBeGreaterThan(0);
+      }
+    });
+
+    it('should execute analyze_document prompt', async () => {
+      const result = await server.executePrompt('analyze_document', {
+        document: 'Sample document content',
+      });
+
+      expect(isOk(result)).toBe(true);
+    });
+
+    it('should return error for unknown prompt', async () => {
+      const result = await server.executePrompt('unknown_prompt', {});
+      expect(isOk(result)).toBe(false);
+    });
+  });
+
+  describe('resource management', () => {
+    it('should list resources', async () => {
+      const result = await server.listResources();
+      expect(isOk(result)).toBe(true);
+      if (isOk(result)) {
+        expect(Array.isArray(result.value)).toBe(true);
+        expect(result.value.length).toBeGreaterThan(0);
+      }
+    });
+
+    it('should read resource', async () => {
+      const result = await server.readResource('katashiro://knowledge/graph');
+      expect(isOk(result)).toBe(true);
+    });
+
+    it('should return error for unknown resource', async () => {
+      const result = await server.readResource('katashiro://unknown/resource');
+      expect(isOk(result)).toBe(false);
+    });
+  });
+});

package/tests/unit/prompt-registry.test.ts

@@ -0,0 +1,193 @@
+/**
+ * PromptRegistry テスト
+ *
+ * @task TSK-062
+ */
+
+import { describe, it, expect, beforeEach } from 'vitest';
+import { PromptRegistry } from '../../src/prompts/prompt-registry.js';
+import { isOk } from '@nahisaho/katashiro-core';
+
+describe('PromptRegistry', () => {
+  let registry: PromptRegistry;
+
+  beforeEach(() => {
+    registry = new PromptRegistry();
+  });
+
+  describe('registration', () => {
+    it('should register a prompt', () => {
+      const result = registry.register({
+        name: 'test_prompt',
+        description: 'A test prompt',
+        template: 'Hello, {{name}}!',
+      });
+
+      expect(isOk(result)).toBe(true);
+    });
+
+    it('should register prompt with arguments', () => {
+      const result = registry.register({
+        name: 'greeting',
+        description: 'Greeting prompt',
+        template: 'Hello, {{name}}! Welcome to {{place}}.',
+        arguments: [
+          { name: 'name', description: 'User name', required: true },
+          { name: 'place', description: 'Location', required: false },
+        ],
+      });
+
+      expect(isOk(result)).toBe(true);
+    });
+
+    it('should reject duplicate registration', () => {
+      registry.register({
+        name: 'test',
+        description: 'First',
+        template: 'First template',
+      });
+
+      const result = registry.register({
+        name: 'test',
+        description: 'Second',
+        template: 'Second template',
+      });
+
+      expect(isOk(result)).toBe(false);
+    });
+  });
+
+  describe('lookup', () => {
+    it('should get registered prompt', () => {
+      registry.register({
+        name: 'my_prompt',
+        description: 'My prompt',
+        template: 'Template',
+      });
+
+      const result = registry.get('my_prompt');
+      expect(isOk(result)).toBe(true);
+      if (isOk(result)) {
+        expect(result.value?.name).toBe('my_prompt');
+      }
+    });
+
+    it('should return null for unknown prompt', () => {
+      const result = registry.get('unknown');
+      expect(isOk(result)).toBe(true);
+      if (isOk(result)) {
+        expect(result.value).toBeNull();
+      }
+    });
+
+    it('should list all prompts', () => {
+      registry.register({
+        name: 'prompt1',
+        description: 'Prompt 1',
+        template: 'T1',
+      });
+      registry.register({
+        name: 'prompt2',
+        description: 'Prompt 2',
+        template: 'T2',
+      });
+
+      const result = registry.list();
+      expect(isOk(result)).toBe(true);
+      if (isOk(result)) {
+        expect(result.value).toHaveLength(2);
+      }
+    });
+  });
+
+  describe('rendering', () => {
+    it('should render template with arguments', () => {
+      registry.register({
+        name: 'greeting',
+        description: 'Greeting',
+        template: 'Hello, {{name}}!',
+      });
+
+      const result = registry.render('greeting', { name: 'World' });
+      expect(isOk(result)).toBe(true);
+      if (isOk(result)) {
+        expect(result.value).toBe('Hello, World!');
+      }
+    });
+
+    it('should render multiple placeholders', () => {
+      registry.register({
+        name: 'intro',
+        description: 'Introduction',
+        template: 'I am {{name}}, age {{age}}, from {{city}}.',
+      });
+
+      const result = registry.render('intro', {
+        name: 'Alice',
+        age: '30',
+        city: 'Tokyo',
+      });
+
+      expect(isOk(result)).toBe(true);
+      if (isOk(result)) {
+        expect(result.value).toBe('I am Alice, age 30, from Tokyo.');
+      }
+    });
+
+    it('should handle missing arguments', () => {
+      registry.register({
+        name: 'test',
+        description: 'Test',
+        template: 'Hello, {{name}}!',
+      });
+
+      const result = registry.render('test', {});
+      expect(isOk(result)).toBe(true);
+      if (isOk(result)) {
+        expect(result.value).toContain('{{name}}');
+      }
+    });
+
+    it('should return error for unknown prompt', () => {
+      const result = registry.render('unknown', {});
+      expect(isOk(result)).toBe(false);
+    });
+  });
+
+  describe('validation', () => {
+    it('should validate required arguments', () => {
+      registry.register({
+        name: 'required_test',
+        description: 'Test required',
+        template: '{{required_arg}}',
+        arguments: [
+          { name: 'required_arg', description: 'Required', required: true },
+        ],
+      });
+
+      const result = registry.validate('required_test', {});
+      expect(isOk(result)).toBe(true);
+      if (isOk(result)) {
+        expect(result.value.valid).toBe(false);
+        expect(result.value.missing).toContain('required_arg');
+      }
+    });
+
+    it('should pass validation with all required args', () => {
+      registry.register({
+        name: 'valid_test',
+        description: 'Test',
+        template: '{{arg}}',
+        arguments: [
+          { name: 'arg', description: 'Arg', required: true },
+        ],
+      });
+
+      const result = registry.validate('valid_test', { arg: 'value' });
+      expect(isOk(result)).toBe(true);
+      if (isOk(result)) {
+        expect(result.value.valid).toBe(true);
+      }
+    });
+  });
+});