content-validity-index-mcp

MCP Server berbasis FastMCP untuk content-validity-index-backend. Memungkinkan AI client (Claude Desktop, Claude Code, Claude Web) menelusuri instrumen, item, dimensi, penugasan expert, dan menghitung Content Validity Index (CVI) lewat antarmuka MCP standar.

Bisa dipakai lewat tiga kanal — stdio, Claude Code, dan Claude Web (claude.ai) — dengan otentikasi memakai Authentik sebagai identity provider (POLA B: issuer yang sama dengan backend, token user diteruskan ke backend).

Arsitektur auth (POLA B)

Backend & web app content-validity-index sudah memakai Authentik. MCP ini konsisten dengan keduanya:

Claude.ai      ──OAuth Authentik──▶ MCP (AuthentikProvider, issuer = backend)
Claude Code/VS ──API key / token──▶ MCP (BearerApiKeyVerifier)
MCP ──teruskan Bearer <token-user>──▶ content-validity-index-backend

• Token diverifikasi seperti backend: RS256 via JWKS (OIDC discovery dari issuer), issuer dicek, audience tidak diverifikasi.

• Klaim groups dipetakan ke role dengan logika yang sama: cvi-admin → admin, selain itu → expert.

• Otorisasi (admin/expert) ditegakkan backend — MCP hanya meneruskan token.

Cara pakai per kanal

1. stdio — Claude Desktop / Claude Code lokal

Client men-spawn proses langsung. Untuk stdio, token user diambil dari BACKEND_API_TOKEN (token Authentik milik Anda).

{
  "mcpServers": {
    "content-validity-index": {
      "command": "uvx",
      "args": [
        "--from",
        "git+https://github.com/cakrawala-tumbuh/content-validity-index-mcp@v0.1.0",
        "content-validity-index-mcp"
      ],
      "env": {
        "BACKEND_API_BASE_URL": "https://cvi-api.example.com",
        "BACKEND_API_TOKEN": "<token-authentik-anda>"
      }
    }
  }
}

Atau via Docker (stdio): command: "docker", args: ["run","--rm","-i","-e","MCP_TRANSPORT=stdio","-e","BACKEND_API_BASE_URL=...","-e","BACKEND_API_TOKEN=...","ghcr.io/cakrawala-tumbuh/content-validity-index-mcp:latest"].

2. Claude Code

# stdio
claude mcp add content-validity-index -- \
  uvx --from "git+https://github.com/cakrawala-tumbuh/content-validity-index-mcp@v0.1.0" \
  content-validity-index-mcp
# remote (server HTTP yang sudah berjalan)
claude mcp add --transport http content-validity-index https://mcp.example.com/mcp

3. Claude Web (claude.ai) — remote, WAJIB OAuth Authentik

Jalankan server sebagai service HTTP di URL publik HTTPS, lalu daftarkan sebagai Custom Connector di claude.ai. Memerlukan konfigurasi Authentik.

docker run -d -p 8000:8000 \
  -e MCP_BASE_URL=https://mcp.example.com \
  -e AUTHENTIK_ISSUER_URL=https://auth.example.com/application/o/cvi/ \
  -e AUTHENTIK_CLIENT_ID=... -e AUTHENTIK_CLIENT_SECRET=... \
  -e AUTHENTIK_ADMIN_GROUP=cvi-admin -e AUTHENTIK_EXPERT_GROUP=cvi-expert \
  -e BACKEND_API_BASE_URL=https://cvi-api.example.com \
  ghcr.io/cakrawala-tumbuh/content-validity-index-mcp:latest

Dirilis via GitHub (GitHub Release + image GHCR). Tidak tersedia di PyPI. Install dari sumber: pip install "git+https://github.com/cakrawala-tumbuh/content-validity-index-mcp@v0.1.0".

Otentikasi (Authentik)

Server memilih auth otomatis dari environment:

Buat OAuth2/OIDC Provider + Application di Authentik (Redirect URI https://<MCP_BASE_URL>/auth/callback, scope openid profile email groups), pakai issuer/slug yang sama dengan backend, lalu isi AUTHENTIK_*. Kontrol akses dilakukan via Policy Binding di Authentik dan role dari groups.

Konfigurasi (environment)

Deployment cloud memakai uvicorn: uvicorn content_validity_index_mcp.asgi:app --host 0.0.0.0 --port 8000.

Tools

Pengembangan

pip install -e .
python -m content_validity_index_mcp     # jalankan lokal (stdio)
make test                                # gate test (lint + unit) di Docker

Lisensi

MIT.