English 中文 العربية 日本語 Português

Skills: Desenvolvimento de Ferramentas Personalizadas

Última atualização: 2026-08-31

Ferramentas integradas não são suficientes? Construa as suas — o protocolo MCP significa que capacidades de Skills não têm limites.

1. Básicos do Protocolo MCP

(1) O que é MCP

Model Context Protocol é o protocolo padrão para ferramentas de IA:

TEXT 📖 Somente leitura 
Arquitetura MCP
┌──────────┐    Protocolo MCP    ┌──────────────┐
│ Cliente IA │ ←──────────────→ │ Servidor MCP  │
│ (Claude)  │                   │ (Ferramenta)  │
└──────────┘                   └──────────────┘
                                      ↕
                                ┌──────────────┐
                                │ Serviço      │
                                │ Externo      │
                                │ (DB/API/Arq) │
                                └──────────────┘

(2) Tipos de Ferramenta

Tipo Descrição Exemplo
Ferramentas de recurso Fornecem leitura de dados Consultas de banco de dados, sistemas de arquivos
Ferramentas de ação Executam operações Enviar email, criar tickets
Ferramentas de prompt Fornecem templates Templates de relatório, checklists de revisão

2. Desenvolvendo Ferramentas Personalizadas

(1) Análise de Requisitos

TEXT 📖 Somente leitura 
Fluxo de Desenvolvimento de Ferramenta Personalizada
1. Identificar necessidades que ferramentas integradas não atendem
2. Definir entrada/saída da ferramenta
3. Escolher implementação (Node.js / Python)
4. Implementar lógica da ferramenta
5. Configurar servidor MCP
6. Vincular e usar na Skill

(2) Implementação Mínima

TYPESCRIPT 
// mcp-server-example/index.ts
import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";

const server = new McpServer({ name: "db-query", version: "1.0.0" });

server.tool("query_database", { sql: { type: "string" } }, async ({ sql }) => {
  const result = await executeQuery(sql);
  return { content: [{ type: "text", text: JSON.stringify(result) }] };
});

const transport = new StdioServerTransport();
await server.connect(transport);

(3) Configuração e Integração

JSON 
{
  "mcpServers": {
    "db-query": {
      "command": "node",
      "args": ["./mcp-servers/db-query/index.js"],
      "env": {
        "DATABASE_URL": "postgresql://localhost/mydb"
      }
    }
  }
}

3. Princípios de Design de Ferramenta

(1) Responsabilidade Única

Cada ferramenta faz uma coisa:

✅ Bom Design ❌ Mau Design
query_database do_database_stuff
send_email communicate
search_logs find_stuff

(2) Validação de Entrada

TYPESCRIPT 
server.tool("query_database", {
  sql: {
    type: "string",
    description: "Instrução SQL (somente SELECT)",
    validate: (sql: string) => {
      if (/^\s*(DROP|DELETE|UPDATE|INSERT|ALTER)/i.test(sql)) {
        throw new Error("Somente consultas SELECT são permitidas");
      }
    }
  }
}, handler);

(3) Tratamento de Erros

TYPESCRIPT 
async ({ sql }) => {
  try {
    const result = await executeQuery(sql);
    return { content: [{ type: "text", text: JSON.stringify(result) }] };
  } catch (error) {
    return {
      content: [{ type: "text", text: `Consulta falhou: ${error.message}` }],
      isError: true
    };
  }
};

4. Depuração e Publicação de Ferramenta

(1) Depuração Local

BASH 
# Executar servidor MCP diretamente para teste
node ./mcp-servers/db-query/index.js

# Enviar requisição de teste
echo '{"method":"tools/list"}' | node ./mcp-servers/db-query/index.js

(2) Logging

TYPESCRIPT 
// Adicionar middleware de logging
server.tool("query_database", { sql: { type: "string" } }, async ({ sql }) => {
  console.error(`[DB-QUERY] SQL: ${sql}`);
  const start = Date.now();
  const result = await executeQuery(sql);
  console.error(`[DB-QUERY] Duração: ${Date.now() - start}ms`);
  return { content: [{ type: "text", text: JSON.stringify(result) }] };
});

(3) Publicação e Distribuição

TEXT 📖 Somente leitura 
Métodos de Publicação
├── Pacote npm: npm publish @your-org/mcp-server-xxx
├── Docker: docker build + docker push
├── Repo Git: Clonar e usar diretamente
└── Template de config: Fornecer template de configuração JSON

5. Prática de Ferramenta Personalizada

▶ Exemplo: Ferramenta de Busca de Logs

Alice desenvolveu uma ferramenta MCP de busca de logs:

YAML 
---
name: log-analyzer
description: "Análise de logs: busca, filtragem, estatísticas"
tools:
  - Read
  - search_logs  # Ferramenta MCP personalizada
---

Bob disse: "O valor das ferramentas personalizadas é conectar IA aos seus sistemas proprietários — onde ferramentas genéricas não alcançam, ferramentas personalizadas preenchem a lacuna."

❓ Perguntas Frequentes

P: Preciso usar TypeScript para ferramentas MCP? R: Não. O protocolo MCP é JSON-RPC; qualquer linguagem pode implementá-lo. SDKs oficiais fornecem versões TypeScript e Python. P: Ferramentas personalizadas têm riscos de segurança? R: Sim. Sempre faça validação de entrada e controle de acesso dentro da ferramenta; não deixe a segurança inteiramente por conta dos prompts da Skill. P: Um servidor MCP pode fornecer múltiplas ferramentas? R: Sim. Mas recomendamos no máximo 5 ferramentas por servidor para manter responsabilidade focada.

📖 Resumo

📝 Exercícios

  1. Básico (⭐): Use o MCP SDK para criar uma ferramenta simples Hello World e integrá-la com uma Skill.
  2. Intermediário (⭐⭐): Desenvolva uma ferramenta MCP de consulta de banco de dados com validação de entrada e tratamento de erros.
  3. Avançado (⭐⭐⭐): Desenvolva uma ferramenta MCP completa de análise de logs com suporte a busca, filtragem e estatísticas, com documentação de depuração e publicação.
Web-Tutorial.com

Equipe Técnica Web-Tutorial

Uma plataforma de tutoriais mantida por diversos desenvolvedores. Cada tutorial é escrito e revisado por profissionais da área correspondente. Trabalhamos para manter nosso conteúdo preciso e confiável — se encontrar algum problema, avise-nos.

100%