@zhama/mcp-server

A TypeScript-based framework for building MCP (Model Context Protocol) servers with tools, resources, and prompts.

🌟 Features

• 🔧 Tool Management: Create custom tools with decorators and type safety
• 📦 Resource Management: Dynamic resource creation and management
• 💬 Prompt Management: Intelligent prompt generation with parameters
• 🔗 Multi-Protocol Support: Both STDIO and SSE connection modes
• 📝 Built-in Logging: Comprehensive logging and error tracking
• ⚡ High Performance: Optimized async architecture
• 🧩 Modular Design: Clean, extensible code structure
• 📚 TypeScript First: Full type safety and IntelliSense support

📋 Requirements

• Node.js >= 18.0.0
• TypeScript >= 4.5.0
• npm >= 8.0.0

🚀 Installation

npm install @zhama/mcp-server

🔧 Quick Start

Basic Server

import { createMCPServer, BaseTool, Tool } from '@zhama/mcp-server';

// Create a custom tool
@Tool({
  name: 'echo',
  description: 'Echoes back the input',
  parameters: [
    {
      name: 'message',
      type: 'string',
      description: 'Message to echo',
      required: true
    }
  ]
})
class EchoTool extends BaseTool {
  protected toolDefinition = {
    name: 'echo',
    description: 'Echoes back the input',
    parameters: []
  };

  protected async executeInternal(parameters: Record<string, unknown>): Promise<unknown> {
    return { echo: parameters.message };
  }
}

// Create and run the server
async function main() {
  const server = createMCPServer('my-server', '1.0.0')
    .description('My custom MCP server')
    .enableTools()
    .addTool(new EchoTool());

  // Run in STDIO mode (for Claude Desktop)
  await server.runStdio();
}

main();

Advanced Server with All Features

import { 
  createMCPServer, 
  BaseTool, 
  BaseResource, 
  BasePrompt,
  Tool 
} from '@zhama/mcp-server';

// Custom tool, resource, and prompt implementations...

const server = createMCPServer('advanced-server', '1.0.0')
  .description('Advanced MCP server with all features')
  .author('Your Name')
  .license('MIT')
  .enableTools({ listChanged: true })
  .enableResources({ subscribe: true, listChanged: true })
  .enablePrompts({ listChanged: true })
  .enableLogging('info')
  .addTool(new MyTool())
  .addResource(new MyResource())
  .addPromptGenerator('my-prompt', async () => {
    // Your prompt generator logic
  });

// Run in SSE mode (for web applications)
await server.runSSE(3000);

📖 Examples

Check out the examples/ directory for complete working examples:

• Basic Server: Simple tool implementation
• Advanced Server: Multiple tools, resources, and prompts
• Custom Implementations: How to extend base classes

Run examples:

# Basic example
npm run example:basic

# Advanced example  
npm run example:advanced

🔧 API Reference

Server Builder

createMCPServer(name: string, version: string)
  .description(desc: string)
  .author(author: string)
  .license(license: string)
  .enableTools(config?: { listChanged?: boolean })
  .enableResources(config?: { subscribe?: boolean; listChanged?: boolean })
  .enablePrompts(config?: { listChanged?: boolean })
  .enableLogging(level?: 'debug' | 'info' | 'warn' | 'error')
  .addTool(tool: BaseTool)
  .addResource(resource: BaseResource)
  .addPromptGenerator(name: string, generator: Function)
  .runStdio(callback?: Function)
  .runSSE(port: number, callback?: Function)

Tool Creation

@Tool({
  name: 'tool-name',
  description: 'Tool description',
  parameters: [
    {
      name: 'param1',
      type: 'string' | 'number' | 'boolean' | 'object' | 'array',
      description: 'Parameter description',
      required: boolean,
      enum?: string[],
      default?: any
    }
  ]
})
class MyTool extends BaseTool {
  protected toolDefinition = {
    name: 'tool-name',
    description: 'Tool description',
    parameters: []
  };

  protected async executeInternal(parameters: Record<string, unknown>): Promise<unknown> {
    // Tool implementation
    return { result: 'success' };
  }
}

Resource Creation

class MyResource extends BaseResource {
  protected resourceDefinition = {
    type: 'text/plain' | 'application/json' | 'image/jpeg' | 'image/png',
    description: 'Resource description'
  };

  protected async executeInternal(content: string): Promise<Resource> {
    return {
      id: 'resource-id',
      uri: 'resource://my-resource',
      name: 'Resource Name',
      description: 'Resource description',
      type: 'application/json',
      content: JSON.stringify({ data: 'example' })
    };
  }
}

Prompt Creation

class MyPrompt extends BasePrompt {
  protected promptDefinition = {
    type: 'text' | 'markdown',
    description: 'Prompt description'
  };

  protected async executeInternal(content: string): Promise<Prompt> {
    return {
      id: 'prompt-id',
      name: 'Prompt Name',
      description: 'Prompt description',
      type: 'text',
      content: `Generated prompt: ${content}`
    };
  }
}

🔗 Integration

Claude Desktop

Add to your Claude Desktop configuration:

{
  "mcpServers": {
    "my-server": {
      "command": "npx",
      "args": ["@zhama/mcp-server", "--stdio"]
    }
  }
}

Custom MCP Client

import { StdioClientTransport } from '@modelcontextprotocol/sdk/client/stdio.js';
import { Client } from '@modelcontextprotocol/sdk/client/index.js';

const transport = new StdioClientTransport({
  command: 'npx',
  args: ['@zhama/mcp-server', '--stdio']
});

const client = new Client({
  name: 'my-client',
  version: '1.0.0'
}, {
  capabilities: {
    tools: {}
  }
});

await client.connect(transport);

🧪 Testing

# Run built-in server
npm run start:stdio

# Test with MCP Inspector
npm run inspector

# Run examples
npm run example:basic -- --stdio
npm run example:advanced -- --stdio

🔧 TypeScript Configuration

Ensure your tsconfig.json includes:

{
  "compilerOptions": {
    "experimentalDecorators": true,
    "emitDecoratorMetadata": true,
    "target": "ES2020",
    "module": "commonjs",
    "strict": true,
    "esModuleInterop": true,
    "skipLibCheck": true,
    "forceConsistentCasingInFileNames": true
  }
}

📦 Module Exports

// Main exports
export { createMCPServer, MCPServerBuilder, UnifiedMCPServer } from '@zhama/mcp-server';

// Tool exports  
export { BaseTool, Tool } from '@zhama/mcp-server/tools';

// Resource exports
export { BaseResource } from '@zhama/mcp-server/resources';

// Prompt exports
export { BasePrompt } from '@zhama/mcp-server/prompts';

// Type exports
export type { ToolDefinition, Resource, Prompt } from '@zhama/mcp-server';

🚀 Deployment

Docker

FROM node:18-alpine
WORKDIR /app
COPY package*.json ./
RUN npm ci --only=production
COPY . .
RUN npm run build
CMD ["node", "dist/server.js"]

Production

# Build the project
npm run build

# Run in production
NODE_ENV=production node dist/server.js --stdio

🤝 Contributing

We welcome contributions! Please see our Contributing Guide for details.

1. Fork the repository
2. Create a feature branch
3. Make your changes
4. Add tests if applicable
5. Submit a pull request

📜 License

This project is licensed under the MIT License. See the LICENSE file for details.

🔗 Links

• MCP Specification
• Examples
• Claude Desktop
• TypeScript Documentation

📞 Support

• 🐛 Issues: GitHub Issues
• 💬 Discussions: GitHub Discussions
• 📧 Email: [email protected]

Made with ❤️ by the zhama-ai Team