Ultra Wiki MCP

Remote MCP Server somente leitura para conectar o ChatGPT Workspace à Wiki oficial do Grupo Ultra, hospedada em Wiki.js 2.x.

O servidor expõe search_pages para localizar documentação por texto livre e get_page para devolver o Markdown original com metadados de origem. A Wiki permanece a fonte da verdade; o MCP apenas fornece uma camada segura de acesso.

Estado atual

POST /mcp: transporte MCP Streamable HTTP, compatível com clientes MCP remotos.
search_pages: busca por texto livre via GraphQL pages.search, com teto seguro.
get_page: leitura por path e locale via GraphQL pages.singleByPath.
GET /health: healthcheck sem consulta nem exposição de credenciais.
Autenticação de saída para Wiki.js com token Bearer somente leitura.
OAuth 2.1 Resource Server em produção, com descoberta RFC 9728, JWT/JWKS e escopo.
Bearer estático (MCP_API_KEY) restrito ao desenvolvimento e MCP Inspector.
Inputs validados, timeout e limites de payload.
Logs estruturados sem token ou conteúdo integral da página.

list_pages permanece pendente para completar o escopo da v0.1.

Pré-requisitos

Node.js 22 ou superior, ou Docker.
Token de API de uma conta de serviço do Wiki.js com permissão somente de leitura.
Para produção, uma URL HTTPS pública para o endpoint MCP.

No Wiki.js, crie uma chave dedicada em Administration > API Access. Não use uma credencial administrativa. Conceda apenas a permissão necessária para ler as páginas que o ChatGPT deve consultar.

Configuração local

Copy-Item .env.example .env

Preencha no .env:

WIKI_API_TOKEN=token-da-conta-de-servico
MCP_AUTH_MODE=api-key
MCP_API_KEY=uma-chave-longa-para-proteger-o-endpoint

Depois execute:

npm install
npm run dev

O servidor inicia por padrão em http://localhost:3001:

Invoke-RestMethod http://localhost:3001/health

Testar com MCP Inspector

Com o servidor ativo, conecte um cliente MCP Streamable HTTP a:

http://localhost:3001/mcp

Envie o header:

Authorization: Bearer <MCP_API_KEY>

Pesquise primeiro:

{
  "query": "admissão",
  "limit": 10,
  "locale": "pt-br"
}

Use o path de um resultado para chamar get_page:

{
  "path": "/caminho-da-pagina",
  "locale": "pt-br"
}

A resposta contém title, path, content, contentType, source, pageId, locale, datas e autor da última atualização. Stack traces e credenciais nunca são retornados pelo MCP.

Docker

Defina WIKI_API_TOKEN, as variáveis OAuth e a URL pública em MCP_BASE_URL, então:

docker compose up --build

A imagem usa Node LTS, build em múltiplos estágios e usuário não-root.

Publicação para o ChatGPT Workspace

Publique o serviço atrás de HTTPS e configure como URL remota:

https://seu-dominio.example.com/mcp

O transporte segue Streamable HTTP e o serviço atua como OAuth 2.1 Resource Server. Ele publica Protected Resource Metadata, valida access tokens JWT pelo JWKS do provedor corporativo e exige o escopo wiki.read. O provedor externo (por exemplo, Entra ID, Auth0 ou Keycloak) continua responsável por login, consentimento, Authorization Code + PKCE e emissão/renovação de tokens.

Produção exige MCP_AUTH_MODE=oauth, OAUTH_ISSUER_URL, OAUTH_JWKS_URL, OAUTH_RESOURCE_URL e OAUTH_AUTHORIZATION_SCOPES. Para Microsoft Entra ID, este último contém o scope totalmente qualificado solicitado pelo ChatGPT; OAUTH_REQUIRED_SCOPES continua contendo o valor curto esperado no claim scp do JWT. Veja a configuração completa em docs/oauth.md e o roteiro operacional em DEPLOY.md.

A documentação oficial da OpenAI descreve Remote MCP Servers por server_url e alerta para limitar tools e revisar os dados compartilhados: MCP e Connectors.

Qualidade

npm test
npm run typecheck
npm run lint
npm run build

O schema GraphQL efetivamente encontrado e as decisões da descoberta estão em docs/wikijs-schema.md.

O procedimento completo para testar, publicar por HTTPS e cadastrar no ChatGPT Workspace está em DEPLOY.md.

Segurança

Nunca commite .env ou tokens.
Não registre cabeçalhos Authorization nem conteúdo integral das páginas.
Não conceda escrita à conta de serviço desta versão.
Não exponha o endpoint MCP sem autenticação em produção.
Não reutilize WIKI_API_TOKEN como token OAuth nem envie esse segredo ao ChatGPT.
Não acesse o PostgreSQL diretamente.