MCP Deep Dive: construindo um servidor profissional

// MCP server em TypeScript — SDK oficial @modelcontextprotocol/sdk
import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
import { z } from "zod";

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

// --- TOOL: ação com efeito controlado pelo modelo
server.registerTool(
  "search_customer_by_email",
  {
    description:
      "Busca dados públicos do cliente por email EXATO. " +
      "NÃO use para busca aproximada — use search_customer_fuzzy para isso. " +
      "Retorna { id, name, plan, signup_at } ou null.",
    inputSchema: {
      email: z.string().email().describe("Email exato do cliente"),
    },
  },
  async ({ email }) => {
    const row = await db.oneOrNone(
      "SELECT id, name, plan, signup_at FROM customers WHERE email = $1",
      [email.toLowerCase()],
    );
    return {
      content: [{ type: "text", text: JSON.stringify(row) }],
    };
  },
);

// --- RESOURCE: dado legível escolhido pelo host/usuário
server.registerResource(
  "customer-doc",
  new ResourceTemplate("customer://{id}/profile", { list: undefined }),
  {
    title: "Perfil do cliente",
    description: "Documento estruturado com histórico resumido.",
  },
  async (uri, { id }) => ({
    contents: [{
      uri: uri.href,
      text: await getCustomerProfileMarkdown(id),
      mimeType: "text/markdown",
    }],
  }),
);

// --- PROMPT: template invocado pelo usuário (slash command)
server.registerPrompt(
  "summarize-customer",
  {
    title: "Resumir cliente",
    description: "Gera resumo executivo do cliente",
    argsSchema: { id: z.string() },
  },
  ({ id }) => ({
    messages: [{
      role: "user",
      content: {
        type: "text",
        text:
          `Resuma em 200 palavras o cliente ${id}: plano, uso, tickets, sinal de churn.`,
      },
    }],
  }),
);

await server.connect(new StdioServerTransport());

// ~/.claude/mcp.json — configuração de MCP servers no host
{
  "mcpServers": {
    "ffv-db": {
      "command": "node",
      "args": ["/Users/ferf/ffv-mcp/dist/server.js"],
      "env": { "DATABASE_URL": "postgres://..." }
    },
    "github": {
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-github"],
      "env": { "GITHUB_PERSONAL_ACCESS_TOKEN": "ghp_..." }
    },
    "acme-saas": {
      "url": "https://mcp.acme.com/v1",
      "headers": { "Authorization": "Bearer $ACME_TOKEN" }
    }
  }
}

# pip install mcp
from mcp.server import Server
from mcp.server.stdio import stdio_server
from mcp.types import TextContent, Tool
import psycopg, os

server = Server("ffv-db-server")
POOL = psycopg.connect(os.environ["DATABASE_URL"])

@server.list_tools()
async def list_tools() -> list[Tool]:
    return [
        Tool(
            name="search_customer_by_email",
            description=(
                "Busca cliente por email EXATO. Não usa match aproximado. "
                "Retorna JSON {id, name, plan, signup_at} ou null."
            ),
            inputSchema={
                "type": "object",
                "properties": {
                    "email": {"type": "string", "format": "email"},
                },
                "required": ["email"],
            },
        ),
    ]

@server.call_tool()
async def call_tool(name: str, arguments: dict) -> list[TextContent]:
    if name == "search_customer_by_email":
        email = arguments["email"].lower()
        with POOL.cursor() as cur:
            cur.execute(
                "SELECT id, name, plan, signup_at FROM customers WHERE email=%s",
                (email,),
            )
            row = cur.fetchone()
        payload = None if not row else {
            "id": row[0], "name": row[1], "plan": row[2], "signup_at": str(row[3]),
        }
        import json
        return [TextContent(type="text", text=json.dumps(payload))]
    raise ValueError(f"Tool desconhecida: {name}")

async def main() -> None:
    async with stdio_server() as (read, write):
        await server.run(read, write, server.create_initialization_options())

if __name__ == "__main__":
    import asyncio
    asyncio.run(main())

// Server HTTP com Hono + MCP SDK + OAuth 2.1
import { Hono } from "hono";
import { bearerAuth } from "hono/bearer-auth";
import { HttpServerTransport } from "@modelcontextprotocol/sdk/server/http.js";

const app = new Hono();

// --- Middleware: auth + rate limit
app.use("/mcp/*", bearerAuth({
  verifyToken: async (token) => {
    const user = await validateJWT(token);
    if (!user) return false;
    c.set("user", user);                // disponível para tools
    return true;
  },
}));
app.use("/mcp/*", rateLimiter({ max: 60, windowMs: 60_000 }));   // 60/min por token

// --- Endpoint MCP
app.post("/mcp/v1", async (c) => {
  const user = c.get("user");
  const server = buildServerForUser(user);      // escopo por user
  const transport = new HttpServerTransport({ request: c.req.raw });
  await server.connect(transport);
  return transport.response;
});

// --- Endpoint OAuth metadata para discovery
app.get("/.well-known/oauth-authorization-server", (c) =>
  c.json({
    issuer: "https://mcp.ffv.com",
    authorization_endpoint: "https://mcp.ffv.com/oauth/authorize",
    token_endpoint: "https://mcp.ffv.com/oauth/token",
    grant_types_supported: ["authorization_code", "refresh_token"],
    code_challenge_methods_supported: ["S256"],
  }),
);

export default app;

// Middleware de log estruturado para cada tool call
server.setRequestMiddleware(async (req, next) => {
  const start = Date.now();
  const user = req.auth?.user;
  try {
    const res = await next();
    logger.info({
      event: "mcp.tool_call",
      tool: req.params?.name,
      user_id: user?.id,
      duration_ms: Date.now() - start,
      status: "ok",
    });
    return res;
  } catch (err) {
    logger.error({
      event: "mcp.tool_call",
      tool: req.params?.name,
      user_id: user?.id,
      duration_ms: Date.now() - start,
      status: "error",
      error: String(err),
    });
    throw err;
  }
});