roshan-fahm-mcp

A self-hostable Model Context Protocol (MCP) server for Roshan AI's Fahm (فهم) Persian language service.

Chat over documents · Translation · Summarization · Text generation · Text correction · Document classification · Information extraction

roshan-fahm-mcp wraps the HTTP API of Fahm (فهم) — Roshan AI's native Persian language-understanding service — and exposes every one of its endpoints as MCP tools. Point any MCP client (Claude, an IDE, an agent framework) at it and give your model first-class Persian chat-over-documents, translation, summarization, generation, correction, classification, and document Q&A.

It is self-hostable and multi-instance: one process can route to several self-hosted Fahm deployments (per tenant / data-center / environment) selected per call via an instance argument. Authentication (SSO via POST /auth/glogin/ → a Bearer access_token, cached and auto-refreshed on 401) is handled for you, and secrets are never logged or returned.

This is an independent, community-maintained integration. It is not an official Roshan AI product. See LICENSE.

Contents

• What it wraps (endpoints)
• Tool reference
• Architecture
• Install
• Configuration
• Connect an MCP client
• Self-hosting, multi-instance & scaling
• Deployment
• Testing & CI
• License

What it wraps (endpoints)

Fahm uses SSO/Bearer auth: a username/password is exchanged for an access_token via POST /auth/glogin/; the token is then sent as Authorization: Bearer <access_token> on every request (you may also supply a static token directly). The client does this transparently, caches the token in memory, and re-logs-in once on a 401.

The host root is https://fahm.roshan-ai.ir; service endpoints live under /api/... and login under /auth/glogin/.

Alefba document URLs. Several tools accept document_urls pointing at Roshan's Alefba system. The URL is the part of the panel image URL between page_image/ and @page (e.g. http://alefba.roshan-ai.ir/media/files/.../sample_persian_1.pdf).

Tool reference

Every tool accepts an optional instance: str | None = None (omit to use the default instance). On bad input or an API error, tools return a structured {"error": ..., "message": ...} payload instead of raising.

Explore everything offline with:

python examples/inspect_server.py

Architecture

How a client request reaches Fahm through the server's tool modules and HTTP client — including the Keycloak SSO login and the Alefba document source:

The authentication flow — SSO login at /auth/glogin/, in-memory Bearer token cache, authenticated /api/... calls, and re-login on 401:

Regenerate the diagrams with make diagrams (or python assets/diagrams/generate_diagrams.py). It rasterizes the official Fahm icon with cairosvg and renders with Graphviz dot.

Install

Requires Python 3.10+.

git clone <this-repo> && cd roshan-fahm-mcp
python3 -m venv .venv && source .venv/bin/activate
pip install -e ".[dev]"              # runtime + test/lint extras
# (optional, for regenerating diagrams)
pip install diagrams cairosvg        # also needs Graphviz `dot` on PATH

Or with Docker:

docker build -t roshan-fahm-mcp .
docker run --rm -p 8000:8000 \
  -e ROSHAN_FAHM_USERNAME=your-user \
  -e ROSHAN_FAHM_PASSWORD=your-pass \
  roshan-fahm-mcp

A docker-compose.yml with two instances and an .env.example (referenced via env_file) are provided too:

cp .env.example .env   # fill in credentials
docker compose up

Configuration

Configuration is entirely environment-driven. There are two styles. base_url is always the host root (the client appends /api/... and /auth/glogin/).

Shorthand (single default instance)

The quickest way to configure the default instance:

export ROSHAN_FAHM_USERNAME=alice
export ROSHAN_FAHM_PASSWORD=s3cr3t

Nested (many named instances)

For multiple self-hosted deployments, use the ROSHAN_FAHM__ namespace with __ as the nesting delimiter:

# Tenant A logs in with credentials; on-prem uses a static token over a
# self-signed cert.
export ROSHAN_FAHM__INSTANCES__TENANTA__BASE_URL=https://fahm.tenant-a.internal
export ROSHAN_FAHM__INSTANCES__TENANTA__USERNAME=alice
export ROSHAN_FAHM__INSTANCES__TENANTA__PASSWORD=s3cr3t
export ROSHAN_FAHM__INSTANCES__ONPREM__BASE_URL=https://fahm.on-prem.local
export ROSHAN_FAHM__INSTANCES__ONPREM__TOKEN=xxxxxxxx
export ROSHAN_FAHM__INSTANCES__ONPREM__VERIFY_SSL=false
export ROSHAN_FAHM__DEFAULT_INSTANCE=tenanta

See .env.example for a complete, ready-to-copy file (default + onprem instances + global settings). If both styles are present, nested config wins for a given instance. The list_instances tool shows what is configured (names and base URLs only).

Connect an MCP client

stdio (local)

Run the server over stdio and register it with your client. Example client configuration:

{
  "mcpServers": {
    "roshan-fahm": {
      "command": "python",
      "args": ["-m", "roshan_fahm_mcp"],
      "env": {
        "ROSHAN_FAHM_BASE_URL": "https://fahm.roshan-ai.ir",
        "ROSHAN_FAHM_USERNAME": "alice",
        "ROSHAN_FAHM_PASSWORD": "s3cr3t"
      }
    }
  }
}

If you installed the package, the console script roshan-fahm-mcp works as the command too.

HTTP (networked)

python -m roshan_fahm_mcp --transport streamable-http --host 0.0.0.0 --port 8000

Then point your client at http://<host>:8000. The sse transport is also available (--transport sse).

Self-hosting, multi-instance & scaling

A single process can route to many self-hosted Fahm deployments, chosen per call via instance, each with its own credentials:

• Self-hosting. Set each instance's BASE_URL to your own Fahm deployment's host root. Use VERIFY_SSL=false for self-signed certificates in development.
• Multi-instance. Configure as many ROSHAN_FAHM__INSTANCES__<NAME>__* blocks as you need; every tool takes an instance argument to pick one. Omit it to use ROSHAN_FAHM__DEFAULT_INSTANCE.
• Scaling. The process is stateless except for an in-memory Bearer token cache per instance, so it scales horizontally — run multiple replicas behind a load balancer. Each replica logs in independently and refreshes on 401. A HorizontalPodAutoscaler is included for Kubernetes.
• Security. Tokens and passwords are never logged and are redacted from error messages; list_instances never returns secrets.

Deployment

Production-ready manifests live in deploy/:

• Helm chart — deploy/helm/roshan-fahm-mcp
• Kubernetes manifests (kustomize) — deploy/kubernetes
• Terraform module — deploy/terraform

Each carries the instance credentials (username / password / token) in a Kubernetes Secret and the non-secret config (base URL, verify_ssl) in a ConfigMap. See deploy/README.md for step-by-step instructions, including multi-instance configuration, ingress, and autoscaling.

Testing & CI

The unit suite is fully offline — all HTTP (including the /auth/glogin/ exchange) is mocked with respx:

python scripts/smoke_test.py        # offline tool sanity check
python -m pytest -q                 # unit tests
ruff check src tests                # lint

CI (GitHub Actions) runs lint + smoke test + pytest across Python 3.10/3.11/3.12 on every push and pull request, builds the Docker image (pushing to GHCR off non-PR events), and on a v* tag builds the sdist/wheel and attaches them to the GitHub Release. Dependabot keeps pip and github-actions dependencies current.

Optional live tests run against a real Fahm deployment when you opt in:

export ROSHAN_FAHM_BASE_URL=https://fahm.roshan-ai.ir
export ROSHAN_FAHM_USERNAME=... ROSHAN_FAHM_PASSWORD=...
export ROSHAN_FAHM_LIVE=1
pytest tests/live -q

License

MIT. "Roshan", "Fahm" (فهم) and related names/logos belong to their respective owners; this project only integrates with their API. Comply with Roshan AI's terms of service when using their service through this server.