wiki-mcp-server

Servidor MCP (Model Context Protocol) serverless na AWS que conecta o Claude a uma wiki interna escrita em Markdown. Os colaboradores entram com o SSO da empresa e fazem perguntas no Claude (web, desktop, mobile ou Slack). O Claude busca e lê as páginas da wiki para responder, citando a fonte.

Sem RAG e sem banco vetorial. A wiki cabe inteira em memória, a busca é lexical e quem interpreta o conteúdo é o próprio modelo. Isso deixa o sistema mais simples, mais barato e mais fácil de auditar.

Arquitetura

flowchart LR
    subgraph CICD["CI/CD"]
        A[Autores<br/>git push + PR] --> R[(Repositório<br/>da wiki)]
        R -->|merge na main| P[Pipeline<br/>tar.gz → S3]
    end

    subgraph AWS["Conta AWS"]
        P --> S3[(S3 privado<br/>versionado)]
        WAF[WAF + ALB<br/>allowlist de IPs<br/>HTTPS] --> L[Lambda<br/>servidor MCP]
        L -->|carrega e indexa<br/>em memória| S3
        L --> CW[CloudWatch<br/>logs e buscas sem resultado]
    end

    subgraph Anthropic
        C[Claude<br/>conector personalizado]
    end

    U[Colaboradores] --> C
    C -->|MCP via HTTPS<br/>+ Bearer token| WAF
    U -.->|login OAuth<br/>uma vez| IdP[Provedor de identidade<br/>Entra ID / Okta / Cognito]
    C -.-> IdP

Fluxo de uma pergunta

1. O colaborador pergunta algo no Claude.

2. O Claude chama o servidor MCP por HTTPS, enviando o token OAuth do usuário.

3. O WAF só deixa passar os IPs de saída da Anthropic. O ALB termina o TLS.

4. A Lambda valida o JWT (assinatura, emissor, audience, expiração e, opcionalmente, o grupo do usuário) e executa a ferramenta pedida.

5. Cada busca vai para o CloudWatch com a quantidade de resultados. As buscas sem resultado mostram onde falta documentação.

Ferramentas expostas ao Claude

Related MCP server: mcp-wikijs

Decisões de design

Estrutura

src/wiki_mcp/
  handler.py   # entrada HTTP (evento do ALB), rotas e resposta 401 com o desafio OAuth
  mcp.py       # JSON-RPC do MCP: initialize, tools/list, tools/call
  wiki.py      # carga, índice em memória, busca e leitura
  auth.py      # validação do JWT via JWKS do IdP
  storage.py   # download do tar.gz do S3 com cache por ETag
  local.py     # servidor local para desenvolvimento
infra/template.yaml       # AWS SAM: S3, Lambda, ALB, WAF, logs
pipeline/buildspec.yml    # CodeBuild: empacota a wiki e publica no S3
wiki/                     # conteúdo de exemplo (empresa fictícia)
tests/                    # pytest

Rodando localmente

python -m venv .venv
source .venv/bin/activate        # Windows: .venv\Scripts\activate
pip install -r requirements-dev.txt
pytest -q

cd src && python -m wiki_mcp.local --wiki ../wiki --port 8000

Teste com o MCP Inspector: rode npx @modelcontextprotocol/inspector, escolha Streamable HTTP e use a URL http://localhost:8000/mcp.

Deploy na AWS

sam build -t infra/template.yaml
sam deploy --guided

Depois do deploy:

1. Aponte o domínio para o LoadBalancerDns (saída do stack).

2. Configure a pipeline (CodePipeline + CodeBuild com pipeline/buildspec.yml, ou GitHub Actions) para publicar wiki.tar.gz no bucket a cada merge.

3. Registre um aplicativo OAuth no IdP e, no Claude, adicione um conector personalizado com a URL McpEndpoint.

Sobre o projeto

Projeto pessoal para explorar como dar a um assistente de IA acesso seguro à base de conhecimento de uma empresa, cobrindo arquitetura serverless na AWS, protocolo MCP, autenticação OAuth/OIDC e infraestrutura como código. O conteúdo da wiki é fictício.

Desenvolvido com IA: a arquitetura, o código e os testes foram feitos em pair programming com o Claude (Claude Code), da discussão do desenho à implementação.

Licença

MIT