convez.ai
MCP ServerDesenvolvimento WebIntermediário
pikkujs

Pikku MCP Template

pikkujs/template-mcp-server

Template boilerplate para servidores MCP em TypeScript com Pikku

Ver no GitHub
InicialPluginScore · de 0 a 100

Template completo para criar servidores MCP (Model Context Protocol) usando Pikku. Demonstra como construir ferramentas e recursos compatíveis com MCP, incluindo geração automática de tipos, suporte a JSON-RPC 2.0 e integração com clientes MCP.

Instalação

$npx convez-ai pikkujs/template-mcp-server

1 comando no terminal: detecta o formato do repositório (marketplace ou plugin avulso) e instala via Claude Code. Requer Node 18+ e o Claude Code instalado.

Métricas

Estrelas
0
Forks
0
Acompanhando
0
Saúde
25%
Último commit
há 1 semana
Versão
—
Issues abertas
0
Contribuidores
1

Casos de uso

  • Aprender como estruturar um servidor MCP do zero
  • Prototipar novas ferramentas e recursos para integração com Claude
  • Scaffolding rápido de projetos MCP com geração automática de schemas

Veredito

Template educacional sólido que demonstra padrões MCP modernos com Pikku. Adequado para quem precisa começar um servidor MCP, mas é um exemplo — confirme se atende suas necessidades específicas antes de usar em produção.

README

A tradução para o português deste README ainda está na fila.

Pikku MCP Template

This template demonstrates how to create a Model Context Protocol (MCP) server using Pikku. It provides a complete example of building MCP-compliant tools and resources with automatic type generation and JSON-RPC 2.0 support.

What's Included

MCP Functions (src/mcp.functions.ts)

  • sayHello: A simple greeting tool that accepts an optional name parameter
  • calculate: A calculator tool that performs basic math operations (add, subtract, multiply, divide)
  • getUserInfo: A mock user information resource that returns user profile data

MCP Routes (src/mcp.routes.ts)

Registers the functions as MCP endpoints using the unified addMCPEndpoint() function with explicit type specification:

  • Tools: sayHello, calculate (type: 'tool')
  • Resources: getUserInfo (type: 'resource')

Generated Files (.pikku/mcp/)

  • mcp.gen.json: MCP tool definitions with JSON schemas
  • pikku-mcp-bootstrap.gen.ts: Bootstrap file that registers all MCP endpoints

Quick Start

  1. Install dependencies:

    yarn install
    
  2. Generate Pikku files:

    yarn prebuild
    
  3. Build the TypeScript:

    yarn build
    
  4. Start the MCP server:

    yarn start
    

Development

For development with auto-reload:

yarn dev

Using with MCP Clients

The server uses stdio transport and can be integrated with any MCP client. Example configuration:

{
  "mcpServers": {
    "pikku-mcp": {
      "command": "node",
      "args": ["dist/mcp-server.js"],
      "cwd": "/path/to/templates/modelcontrolprotocol"
    }
  }
}

Example Tool Calls

Say Hello

{
  "jsonrpc": "2.0",
  "id": "1",
  "method": "tools/call",
  "params": {
    "name": "sayHello",
    "arguments": {
      "name": "Claude"
    }
  }
}

Response:

{
  "jsonrpc": "2.0",
  "id": "1",
  "result": {
    "content": [
      {
        "type": "text",
        "text": "{\"message\": \"Hello, Claude! This is a Pikku MCP tool.\", \"timestamp\": 1704067200000}"
      }
    ]
  }
}

Calculate

{
  "jsonrpc": "2.0",
  "id": "2",
  "method": "tools/call",
  "params": {
    "name": "calculate",
    "arguments": {
      "operation": "add",
      "a": 5,
      "b": 3
    }
  }
}

Response:

{
  "jsonrpc": "2.0",
  "id": "2",
  "result": {
    "content": [
      {
        "type": "text",
        "text": "{\"result\": 8, \"operation\": \"5 add 3 = 8\"}"
      }
    ]
  }
}

Get User Info (Resource)

{
  "jsonrpc": "2.0",
  "id": "3",
  "method": "resources/read",
  "params": {
    "uri": "user://123"
  }
}

Response:

{
  "jsonrpc": "2.0",
  "id": "3",
  "result": {
    "contents": [
      {
        "uri": "user://123",
        "mimeType": "application/json",
        "text": "{\"userId\": \"123\", \"name\": \"John Doe\", \"email\": \"john@example.com\", \"lastLogin\": \"2024-01-15T10:30:00Z\"}"
      }
    ]
  }
}

Key Features Demonstrated

  • Unified MCP API: Using addMCPEndpoint() with explicit type specification
  • Inline Type Definitions: Using inline schemas instead of separate interfaces
  • Mixed Tool Types: Both tools and resources in the same application
  • Automatic Schema Generation: JSON schemas generated from TypeScript types
  • Full MCP Compliance: Works with any MCP client using the official SDK
  • Error Handling: Proper JSON-RPC 2.0 error responses
  • Type Safety: Full TypeScript support throughout
  • Organized Output: Files generated in organized directory structure

Architecture

This template uses:

  • @pikku/core: Core Pikku framework for function definitions
  • @pikku/cli: Code generation for MCP schemas and bootstrap files
  • @pikku/mcp-server: MCP server runtime using the official MCP SDK
  • stdio transport: Standard input/output for MCP communication
  • JSON-RPC 2.0: Compliant protocol implementation

Extending

To add new MCP endpoints:

  1. Define functions in src/mcp.functions.ts with inline types
  2. Register them in src/mcp.routes.ts using addMCPEndpoint()
  3. Run yarn prebuild to regenerate schemas
  4. Restart the server

The Pikku CLI will automatically generate the necessary JSON schemas and bootstrap code.

Ver o original no GitHub

Bom para

Relacionados