Servicio read-only que expone la wiki de Pampling (Wiki.js) con dos
interfaces sobre el mismo cliente GraphQL:
- MCP (Streamable HTTP, en
/mcp/) — para agentes IA: Claude Code, Codex, ChatGPT...- API REST (en
/api/*) — para apps no-MCP del servidor: scripts, servicios PHP/Node, crons.Cualquier consumidor accede sin tocar el GraphQL de Wiki.js ni manejar tokens.
| Contexto | URL |
|---|---|
| Internet / agentes externos | https://wiki-mcp.pampl.ing/mcp/ |
Otras apps del servidor (red Docker coolify) |
http://wiki-mcp:8000/mcp/ |
| Desarrollo local | http://127.0.0.1:8000/mcp/ |
| Contexto | URL base |
|---|---|
| Internet | https://wiki-mcp.pampl.ing/api |
| Otras apps del servidor | http://wiki-mcp:8000/api |
| Desarrollo local | http://127.0.0.1:8000/api |
Documentación interactiva (Swagger UI): https://wiki-mcp.pampl.ing/docs.
Schema OpenAPI: https://wiki-mcp.pampl.ing/openapi.json.
Health check público: https://wiki-mcp.pampl.ing/health → {"status":"ok"}.
Sin autenticación en v1: las URLs son públicas. El WIKI_TOKEN que el servicio
usa contra Wiki.js vive solo dentro del contenedor.
Cinco operaciones, expuestas tanto como tools MCP como endpoints REST sobre el mismo WikiClient.
| Operación | Tool MCP | Endpoint REST |
|---|---|---|
| Listar páginas | list_pages(tag?) |
GET /api/pages?tag=... |
| Búsqueda full-text | search(query, limit?) |
GET /api/search?q=...&limit=... |
| Leer página por path | read_page(path) |
GET /api/pages/{path} |
| Leer página por id | read_page(id) |
— (solo MCP) |
| Sidebar | get_navigation() |
GET /api/navigation |
| Tags con conteo | list_tags() |
GET /api/tags |
Detalle por operación:
list_pages(tag?)Devuelve el catálogo completo de páginas. Útil como primer paso de descubrimiento.
Input: tag (opcional, case-insensitive).
Output: lista de páginas con id, path, locale, title, description, tags, updatedAt + total.
{ "tag": "infraestructura" }
search(query, limit?=10)Búsqueda full-text con el motor de Wiki.js. Cap a 50 hits.
Output: lista de resultados con id, path, title, description, snippet (= description en v1), tags + total.
{ "query": "calculo stock", "limit": 10 }
read_page(path? | id?)Lee una página completa. Acepta uno de los dos.
Path admite home, /home, en/home, /en/home. Si no lleva prefijo de locale, usa WIKI_LOCALE (por defecto en).
Output: id, path, title, description, tags, content (markdown crudo), contentType, updatedAt, url (link público).
{ "path": "infraestructura/servidor" }
get_navigation()Estructura jerárquica del sidebar. Headers como secciones que agrupan sus links hijos.
{
"sections": [
{ "label": "Inicio", "type": "link", "target": "/en/home" },
{
"label": "Infraestructura",
"type": "header",
"children": [
{ "label": "Servidor", "target": "/en/infraestructura/servidor" },
{ "label": "Coolify", "target": "/en/infraestructura/coolify" }
]
}
]
}
list_tags()Tags usados en la wiki con conteo de páginas, ordenados por uso desc.
{ "tags": [
{ "tag": "infraestructura", "count": 17 },
{ "tag": "claude-code", "count": 7 }
] }
claude mcp add --scope user --transport http pampling-wiki https://wiki-mcp.pampl.ing/mcp/
--scope user lo deja disponible en todos tus proyectos (~/.claude.json).
Para registrarlo solo en un proyecto, usa --scope project desde la raíz del repo.
Verificación: claude mcp list o /mcp dentro de la sesión.
En ~/.codex/config.toml:
[[mcp_servers]]
name = "pampling-wiki"
url = "https://wiki-mcp.pampl.ing/mcp/"
transport = "streamable-http"
Si tu versión soporta Streamable HTTP nativamente, usa el mismo bloque que Claude Code. Si solo soporta stdio (versiones antiguas), usa el bridge mcp-remote:
{
"mcpServers": {
"pampling-wiki": {
"command": "npx",
"args": ["-y", "mcp-remote", "https://wiki-mcp.pampl.ing/mcp/"]
}
}
}
Archivo: %APPDATA%\Claude\claude_desktop_config.json (Windows) o ~/Library/Application Support/Claude/claude_desktop_config.json (macOS).
Mismo patrón: name + url + transport: streamable-http.
Llaman al API REST en el alias interno, sin pasar por dominio público:
# Listar páginas con tag
curl http://wiki-mcp:8000/api/pages?tag=infraestructura
# Búsqueda
curl 'http://wiki-mcp:8000/api/search?q=stock&limit=5'
# Leer una página
curl http://wiki-mcp:8000/api/pages/infraestructura/servidor
# Sidebar
curl http://wiki-mcp:8000/api/navigation
# Tags
curl http://wiki-mcp:8000/api/tags
Ejemplo PHP:
$pages = json_decode(file_get_contents(
'http://wiki-mcp:8000/api/search?q=' . urlencode('coolify')
), true);
Ejemplo Node:
const res = await fetch('http://wiki-mcp:8000/api/pages/home');
const page = await res.json();
console.log(page.content); // markdown crudo
Para explorar el API y probar requests, abrir https://wiki-mcp.pampl.ing/docs.
| Variable | Default | Descripción |
|---|---|---|
WIKI_URL |
https://wiki.pampl.ing/graphql |
Endpoint GraphQL de Wiki.js |
WIKI_TOKEN |
(requerido, secret) | Token admin de Wiki.js |
WIKI_LOCALE |
en |
Locale por defecto |
MCP_LOG_LEVEL |
info |
debug / info / warning / error |
El WIKI_TOKEN no se expone al cliente MCP — el servidor lo usa internamente.
| Recurso | Valor |
|---|---|
| Repo | pampling/pampling-wiki-mcp (Bitbucket) |
| Coolify project | WIKI (eg4znm0s1wx91ztke1tpjlhu) |
| App UUID | adarfnnloel5ksfkwx5kv64u |
| Build pack | nixpacks |
| Puerto | 8000 |
| Network alias | wiki-mcp (red Docker coolify) |
| Healthcheck | /health |
| Base de datos | — (stateless) |
Stack: Python 3.12 · FastMCP (SDK oficial MCP) · FastAPI · httpx async · Pydantic v2.
Push a main y reinicio:
git push origin main
curl -s -X POST \
-H 'Authorization: Bearer <COOLIFY_TOKEN>' \
-d '{}' \
http://192.168.1.10:8000/api/v1/applications/adarfnnloel5ksfkwx5kv64u/restart
Health a los ~30 s: curl https://wiki-mcp.pampl.ing/health.
curl -H 'Authorization: Bearer <COOLIFY_TOKEN>' \
http://192.168.1.10:8000/api/v1/applications/adarfnnloel5ksfkwx5kv64u/logs
Logs estructurados JSON: cada llamada GraphQL emite {"event": "gql_ok", "latency_ms": ...} o gql_error.
WIKI_TOKENcurl -X PATCH ... /api/v1/applications/adarfnnloel5ksfkwx5kv64u/envs/<env_uuid> -d '{"value":"..."}'
snippet de búsqueda = description de la página. Para snippet contextual real hay que hacer read_page y procesar.| Mejora | Cuándo tiene sentido |
|---|---|
| Caché en memoria (TTL ~60 s) | Si hay muchas llamadas concurrentes |
| Rate limiting | Si la URL pública recibe abuso |
| Búsqueda semántica con embeddings | Si la búsqueda full-text se queda corta para queries en lenguaje natural |
Tool get_recent_changes |
Para alertas de actualizaciones |
Tools de escritura (create_page, update_page) |
Solo si hay caso de uso real con token y permisos separados |
Métricas Prometheus en /metrics |
Si se monta observabilidad central |
Spec versión 1.0 — Abril 2026. Conservada en C:\Users\User\claude-code\specs\wiki-mcp-spec.md (no se commitea al repo del MCP).