Template MCP Server

Um modelo de CLI para inicializar rapidamente um servidor MCP com FastMCP, suportando transporte stdio e HTTP.

GitHub
76
Experimente este MCPPatrocinado

Documentação

@mcpdotdirect/template-mcp-server

License: MIT TypeScript

Uma ferramenta CLI para começar rapidamente a construir seu próprio servidor MCP (Model Context Protocol) usando FastMCP

📋 Uso

# with npx
npx @mcpdotdirect/create-mcp-server

# Or with npm
npm init @mcpdotdirect/mcp-server

🔭 O que está incluído

O template inclui:

  • Configuração básica do servidor com opções de transporte stdio e HTTP usando FastMCP
  • Estrutura para definir ferramentas, recursos e prompts do MCP
  • Configuração TypeScript
  • Scripts de desenvolvimento e configuração

✨ Recursos

  • FastMCP: Construído usando o framework FastMCP para implementação mais simples
  • Suporte a Transporte Duplo: Execute seu servidor MCP via stdio ou HTTP
  • TypeScript: Suporte completo a TypeScript para segurança de tipos
  • Extensível: Fácil de adicionar ferramentas, recursos e prompts personalizados

🚀 Começando

Após criar seu projeto:

  1. Instale as dependências usando seu gerenciador de pacotes preferido:

    # Using npm
npm install

# Using yarn
yarn

# Using pnpm
pnpm install

# Using bun
bun install

  2. Inicie o servidor:

    # Start the stdio server
npm start

# Or start the HTTP server
npm run start:http

  3. Para desenvolvimento com recarga automática:

    # Development mode with stdio
npm run dev

# Development mode with HTTP
npm run dev:http

Nota: Os scripts padrão no package.json usam Bun como runtime (por exemplo, bun run src/index.ts). Se você preferir usar um gerenciador de pacotes ou runtime diferente, pode modificar esses scripts no seu arquivo package.json para usar Node.js ou outro runtime de sua escolha.

📖 Uso Detalhado

Métodos de Transporte

O servidor MCP suporta dois métodos de transporte:

  1. Transporte stdio (Modo Linha de Comando):

    • Executa na sua máquina local
    • Gerenciado automaticamente pelo Cursor
    • Comunica-se diretamente via stdout
    • Acessível apenas por você localmente
    • Ideal para desenvolvimento pessoal e ferramentas

  2. Transporte SSE (Modo Web HTTP):

    • Pode executar localmente ou remotamente
    • Gerenciado e executado por você
    • Comunica-se pela rede
    • Pode ser compartilhado entre máquinas
    • Ideal para colaboração em equipe e ferramentas compartilhadas

Executando o Servidor Localmente

Transporte stdio (Modo CLI)

Inicie o servidor no modo stdio para ferramentas CLI:

# Start the stdio server
npm start
# or with other package managers
yarn start
pnpm start
bun start

# Start the server in development mode with auto-reload
npm run dev
# or
yarn dev
pnpm dev
bun dev

Transporte HTTP (Modo Web)

Inicie o servidor no modo HTTP para aplicações web:

# Start the HTTP server
npm run start:http
# or
yarn start:http
pnpm start:http
bun start:http

# Start the HTTP server in development mode with auto-reload
npm run dev:http
# or
yarn dev:http
pnpm dev:http
bun dev:http

Por padrão, o servidor HTTP executa na porta 3001. Você pode alterar isso definindo a variável de ambiente PORT:

# Start the HTTP server on a custom port
PORT=8080 npm run start:http

Conectando-se ao Servidor

Conectando-se pelo Cursor

Para conectar seu servidor MCP pelo Cursor:

  1. Abra o Cursor e vá para Configurações (ícone de engrenagem no canto inferior esquerdo)
  2. Clique em "Features" na barra lateral esquerda
  3. Role para baixo até a seção "MCP Servers"
  4. Clique em "Add new MCP server"
  5. Insira os seguintes detalhes:
    • Nome do servidor: my-mcp-server (ou qualquer nome que preferir)
    • Para o modo stdio:
      • Tipo: command
      • Comando: O caminho para o executável do seu servidor, por exemplo, npm start
    • Para o modo SSE:
      • Tipo: url
      • URL: http://localhost:3001/sse
  6. Clique em "Save"

Usando mcp.json com o Cursor

Para uma configuração mais portátil, crie um arquivo .cursor/mcp.json no diretório raiz do seu projeto:

{
  "mcpServers": {
    "my-mcp-stdio": {
      "command": "npm",
      "args": [
        "start"
      ],
      "env": {
        "NODE_ENV": "development"
      }
    },
    "my-mcp-sse": {
      "url": "http://localhost:3001/sse"
    }
  }
}

Você também pode criar uma configuração global em ~/.cursor/mcp.json para disponibilizar seus servidores MCP em todos os seus workspaces do Cursor.

Nota:

  • As entradas do tipo command executam o servidor no modo stdio
  • A entrada do tipo url conecta-se ao servidor HTTP usando transporte SSE
  • Você pode fornecer variáveis de ambiente usando o campo env
  • Ao conectar via SSE com FastMCP, use a URL completa incluindo o caminho /sse: http://localhost:3001/sse

Testando Seu Servidor com Ferramentas CLI

O FastMCP fornece ferramentas integradas para testar seu servidor:

# Test with mcp-cli
npx fastmcp dev server.js

# Inspect with MCP Inspector
npx fastmcp inspect server.ts

Usando Variáveis de Ambiente

Você pode personalizar o servidor usando variáveis de ambiente:

# Change the HTTP port (default is 3001)
PORT=8080 npm run start:http

# Change the host binding (default is 0.0.0.0)
HOST=127.0.0.1 npm run start:http

🛠️ Adicionando Ferramentas e Recursos Personalizados

Ao adicionar ferramentas, recursos ou prompts personalizados ao seu servidor FastMCP:

Ferramentas

server.addTool({
  name: "hello_world",
  description: "A simple hello world tool",
  parameters: z.object({
    name: z.string().describe("Name to greet")
  }),
  execute: async (params) => {
    return `Hello, ${params.name}!`;
  }
});

Recursos

server.addResourceTemplate({
  uriTemplate: "example://{id}",
  name: "Example Resource",
  mimeType: "text/plain",
  arguments: [
    {
      name: "id",
      description: "Resource ID",
      required: true,
    },
  ],
  async load({ id }) {
    return {
      text: `This is an example resource with ID: ${id}`
    };
  }
});

Prompts

server.addPrompt({
  name: "greeting",
  description: "A simple greeting prompt",
  arguments: [
    {
      name: "name",
      description: "Name to greet",
      required: true,
    },
  ],
  load: async ({ name }) => {
    return `Hello, ${name}! How can I help you today?`;
  }
});

📚 Documentação

Para mais informações sobre o FastMCP, visite o Repositório do FastMCP no GitHub.

Para mais informações sobre o Model Context Protocol, visite a Documentação do MCP.

📄 Licença

Este projeto está licenciado sob a Licença MIT - consulte o arquivo LICENSE para obter detalhes.