hana-developer-cli-tool-example mcp-server-development.instructions.md

MCP Server Development Guidelines

Use this guide when creating or modifying TypeScript files in the mcp-server/src/ directory.

Scope and Purpose

This guide applies to all TypeScript files implementing the Model Context Protocol (MCP) server that exposes hana-cli commands as MCP tools, resources, and prompts for LLM consumption.

Critical Principles

1. JSON-RPC Protocol Compliance: MCP communicates via JSON-RPC over STDIO
2. Logging Discipline: ONLY use console.error() for logging, NEVER console.log()
3. Tool Naming: Sanitize tool names to [a-z0-9_-] character set only
4. Schema Generation: Convert yargs builders to JSON Schema accurately
5. Error Enrichment: Provide actionable error analysis and suggestions
6. Type Safety: Use TypeScript interfaces and explicit typing throughout
7. CLI Integration: Maintain consistency with CLI command metadata and structure

CRITICAL: Logging Rules

NEVER write to stdout using console.log() - it will break the JSON-RPC protocol.

// ❌ WRONG - Breaks MCP protocol
console.log('Debug info:', data);
console.log(JSON.stringify(result));

// ✅ CORRECT - Write to stderr
console.error('[MCP Debug]', data);
console.error('[MCP Info]', JSON.stringify(result));

Why: MCP clients expect ONLY JSON-RPC messages on stdout. Any other output causes parsing failures like "Failed to parse message: ...".

Apply to:

• The main index.ts file header comment documents this
• All imported modules that might log (executor.ts, command-parser.ts, etc.)
• Error handling and debugging code

File Structure and Organization

Main Entry Point: index.ts

#!/usr/bin/env node

/**
 * MCP Server for SAP HANA CLI
 * 
 * CRITICAL: This file implements the Model Context Protocol (MCP) server.
 * MCP communicates via JSON-RPC over STDIO. All logging MUST use console.error()
 * to write to stderr, never console.log() which writes to stdout.
 */

import { Server } from '@modelcontextprotocol/sdk/server/index.js';
import { StdioServerTransport } from '@modelcontextprotocol/sdk/server/stdio.js';
// ... more imports

class HanaCliMcpServer {
  private server: Server;
  private commands: Map<string, any> = new Map();

  constructor() {
    this.server = new Server(
      {
        name: 'hana-cli-mcp-server',
        version: '1.0.0',
        icons: [/* icon configuration */],
      },
      {
        capabilities: {
          tools: {},
          resources: {},
          prompts: {},
        },
      }
    );

    this.setupHandlers();
    this.setupErrorHandling();
  }

  private setupHandlers(): void {
    // Register handlers for tools, resources, prompts
  }

  private setupErrorHandling(): void {
    this.server.onerror = (error) => {
      console.error('[MCP Error]', error);
    };

    process.on('SIGINT', async () => {
      await this.server.close();
      process.exit(0);
    });
  }

  async run(): Promise<void> {
    const transport = new StdioServerTransport();
    await this.server.connect(transport);
    console.error('[MCP Server] Running on stdio');
  }
}

const server = new HanaCliMcpServer();
server.run().catch(console.error);