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:

Mekanisme	Untuk	Aktif jika
OAuth Authentik	Claude Web / browser	AUTHENTIK_ISSUER_URL + CLIENT_ID + CLIENT_SECRET + MCP_BASE_URL diisi
API Key statis	VS Code / CLI	MCP_API_KEY diisi (Authorization: Bearer <key>)
(tanpa auth)	stdio / jaringan lokal	tidak ada yang diisi

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)

Variabel	Default	Keterangan
BACKEND_API_BASE_URL	http://localhost:8000	Base URL backend (tanpa /api/v1)
BACKEND_API_TOKEN	—	Token Authentik untuk pemakaian stdio/lokal
MCP_TRANSPORT	stdio	stdio, http, atau sse
MCP_HOST / MCP_PORT	127.0.0.1 / 8000	bind saat http/sse
MCP_BASE_URL	—	URL publik (wajib untuk OAuth Authentik)
AUTHENTIK_ISSUER_URL	—	Issuer OIDC (sama dengan backend)
AUTHENTIK_CLIENT_ID / _SECRET	—	Kredensial OAuth2 Provider
AUTHENTIK_ADMIN_GROUP	cvi-admin	Group → role admin
AUTHENTIK_EXPERT_GROUP	cvi-expert	Group → role expert
MCP_API_KEY	—	API key untuk klien non-OAuth

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

Tools

Tool	Deskripsi
whoami	Sinkronkan & tampilkan profil + role user (POST /auth/sync)
list_instruments	Daftar instrumen yang dapat diakses user
get_instrument	Detail satu instrumen
list_instrument_items	Daftar item pada instrumen
list_instrument_domains	Daftar dimensi/domain pada instrumen (termasuk background_color)
create_instrument_domain	Buat dimensi/domain baru, termasuk warna latar background_color (admin)
update_instrument_domain	Perbarui dimensi/domain, termasuk warna latar background_color (admin)
delete_instrument_domain	Hapus dimensi/domain dari instrumen (admin)
calculate_cvi	Hitung hasil CVI (I-CVI, S-CVI) sebuah instrumen (admin)
list_my_assignments	Daftar penugasan penilaian milik expert
list_assignment_ratings	Daftar rating pada sebuah penugasan

Pengembangan

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

Lisensi

MIT.