gribs_mcp

MCP server for gribs.net — the Grünen-intern (party-internal), login-pflichtige KPV-Bayern platform hosting the Antragsbörse (Musteranträge, Beschlüsse, Positionspapiere) and secondary sections like Wissenswert, Mitgliederbriefe, and Mitgliederversammlungen.

This server exposes gribs.net content to AI harnesses (OpenCode) via the Model Context Protocol, giving an AI assistant read-only access to search and browse Antragsbörse posts and fetch the newest public posts. It is read-only by design — no writing, no triage, no uploads — and only surfaces content the running user is already authorized to see (login is handled via the user's own gribs.net credentials, cached locally).

Every politically relevant result carries a source URL and retrieval timestamp (Quellenpflicht) so downstream tools can cite where a claim came from and when it was fetched.

Tools

All tools are async, annotated readOnlyHint=True, and clamp limit parameters to [1, MAX]. Every result model carries url: str and retrieved_at: datetime (UTC).

Tool	Description	Returns
search_antraege(query, category?, whole_word?, l1?, l2?, l3?, limit?)	Full-text search across a gribs section (default: Antragsbörse). Up to 50 hits. Pass l1/l2/l3 to scope to a subcategory.	list[SearchHit] — title, snippet, wp_id, url, retrieved_at
get_antrag(post_id)	Fetch a single post (antrag) in full detail.	PostDetail — title, date, view_count, share_url, category_breadcrumb, body_html, body_text, url, retrieved_at
resolve_post_id(wp_id)	Resolve a WordPress wp_id (from search_antraege) to the internal post_id required by get_antrag.	PostIdRef — wp_id, post_id, url, retrieved_at
list_categories(category?)	Enumerate the top-level (L1) sub-categories within a section (e.g. Umwelt, Soziales, …).	CategoryNode — id, label, children (recursive)
list_antraege_in_category(category?, l1?, l2?, l3?, limit?)	Drill into the category tree without a search query. Returns subcategories for intermediate nodes; leaves return an empty expansion (use search_antraege with l1/l2/l3 to list posts in a leaf).	StructureExpansion — subcategories (list[CategoryNode]) or posts (list[PostTeaser])
recent_posts(limit?)	Fetch the newest posts from the public gribs.net homepage (no login required). Enrichment is concurrent.	list[PostTeaser] — post_id, title, date, url, retrieved_at
extract_downloads(post_id)	Extract download links (PDFs and download-looking anchors) from a post body.	list[Download] — url, link_text, filename, is_pdf, source_post_id, source_url, retrieved_at

Quellenpflicht: every tool that returns politically relevant data includes url + retrieved_at on each item. This is enforced at the Pydantic model layer, not by convention.

Library stack

Aufgabe	Library	Lizenz
MCP framework	mcp (FastMCP)	MIT
HTTP client	httpx	BSD-3-Clause
Output models	pydantic	MIT
HTML parsing (structure)	selectolax	MIT
Article body extraction	trafilatura	Apache-2.0
OS credential/cookie storage	keyring	MIT

No Playwright. gribs.net's simple form-POST login (no SSO, no JS handshake, no CSRF) does not require a browser — pure httpx is sufficient and dramatically simpler. There is no uv run playwright install step.

Setup

# 1. Install dependencies (uv manages a virtualenv automatically).
uv sync

# 2. Store your gribs.net credentials in the OS keyring.
#    This prompts for email + password via getpass (password is not echoed)
#    and optionally performs a test login to verify the credentials work.
uv run python -m gribs_mcp.auth

# 3. (Optional) Smoke-test the server over stdio.
uv run gribs-mcp

For CI / headless setups, fall back to environment variables (the keyring is checked first, then env vars):

export GRIBS_EMAIL="you@example.org"
export GRIBS_PASSWORD="…"

Cookies are cached in the OS keyring under service name gribs_mcp and are automatically refreshed when they expire (30-day TTL) or when the API returns 401/403. There is no browser profile to manage.

Configure in OpenCode

Register gribs-mcp as a stdio MCP server in your opencode.json (analog to allgaeuer_zeitung_mcp):

{
  "mcp": {
    "gribs_mcp": {
      "type": "stdio",
      "command": "uv",
      "args": ["run", "--directory", "/path/to/gribs_mcp", "gribs-mcp"],
      "enabled": true
    }
  }
}

Replace /path/to/gribs_mcp with the absolute path to this checkout. The gribs-mcp script entry point is defined in pyproject.toml ([project.scripts]).

Development

uv sync                       # install dev deps
uv run ruff check             # lint (E/F/I/UP/B/SIM ruleset)
uv run ruff format --check    # format check
uv run mypy src/              # strict type check
uv run pytest                 # tests (deterministic, no live HTTP)

All four gates must pass before merging. Tests use HTML/JSON fixtures under tests/fixtures/ — no live gribs.net calls, so they run offline and deterministically.

Architecture

src/gribs_mcp/
├── __main__.py   # main() -> mcp.run(transport="stdio")
├── server.py     # FastMCP instance + 7 @mcp.tool definitions (read-only)
├── models.py     # Pydantic v2 models (frozen) with Quellenpflicht fields
├── client.py     # httpx.AsyncClient + cookie jar + auth retry (GribsClient)
├── parsers.py    # Pure HTML/JSON parsers (selectolax + trafilatura)
└── auth.py       # keyring credential + cookie cache (30-day TTL)

Key design decisions:

• httpx-only login — gribs.net uses a plain form-POST to /users/ajax_login with no SSO, no JS handshake, no CSRF token. A browser (Playwright) would be pure overhead. The client does a single httpx.AsyncClient.post and captures the Set-Cookie session cookie.
• Keyring cookie cache — credentials and session cookies are persisted in the OS keyring (service gribs_mcp), not on disk. A 30-day TTL plus per-cookie expires checks gate freshness; on 401/403 the client clears the cache and re-logs in (serialized by an asyncio.Lock to avoid concurrent-login races).
• JSON vs HTML response handling — gribs is inconsistent: /members/structure, /members/singlepost, and /members/expandStructure return JSON {error, ...} with HTML snippets inside; /members/search and /post/recentposts return raw HTML. The client has separate _post_form_json / _post_form_html paths sharing one retry helper.
• HTML-entity-encoded onclick args — the live structexp(...) calls in navigation HTML encode their object's quotes as ". Parsers call html.unescape() before parsing the JS object (shared _parse_js_object helper).
• Concurrent enrichment — recent_posts fetches the scaffold, then fires all postWidgetFill enrichment calls concurrently via asyncio.gather (3 parallel requests for the default 3 posts). Order is preserved (gather guarantees positional ordering).
• Read-only tools + Quellenpflicht — every tool is annotated readOnlyHint=True; every politically relevant output model carries url: str + retrieved_at: datetime (UTC) at the Pydantic schema level, so a missing source is a type error, not a convention violation.

Categories (live-verified)

The category parameter on search_antraege, list_categories, and list_antraege_in_category accepts these names:

Category name	cat_id	Status
Antragsbörse	1	verified
Wissenswert	2	verified
Arbeit im Rat	5	verified
Mitgliederbriefe	6	verified
DenkWerkstatt	7	verified
Mitgliederversammlungen	8	verified
Kommunalwahl	9	verified

Known limitations / roadmap

• list_antraege_in_category on leaf nodes returns an empty expansion — gribs.net's /members/expandStructure returns a search form (not post listings) when called on a leaf subcategory. To list posts in a subcategory, call search_antraege with the same l1/l2/l3 ids and a broad query (e.g. 'a' or 'der' — gribs doesn't support an empty searchstring).
• extract_downloads keyword heuristic — links are included if the URL ends in .pdf OR the anchor text contains a download keyword (download/pdf/antrag/vorlage/beschluss/musterantrag/herunterladen). This may produce false positives (e.g. a non-download link mentioning "antrag") or miss downloads with non-standard anchor text. The is_pdf flag distinguishes confirmed PDFs.

Reverse-engineering notes

Key facts about the gribs.net API (verified live 2026-07-18):

• Login: POST /users/ajax_login with email, password, keep=true. No SSO, no CSRF. Returns a 15-byte non-JSON status; success is signalled by Set-Cookie.
• API shape: all calls are POST application/x-www-form-urlencoded with header X-Requested-With: XMLHttpRequest. Responses are either JSON {error, ...} with HTML snippets inside (structure, singlepost, expandStructure) or raw HTML (search, recentposts).
• ID duality: posts have an internal post_id (needed by /members/singlepost) AND a WordPress wp-ID (returned by /members/search in ?wp=<id> deep-links), plus an optional ?h=<hash> share link. Use resolve_post_id to bridge wp_id → post_id.
• wp_id → post_id resolution: GET /?wp=<id> with follow_redirects=True returns the member page at /members/home/wp-<id>, which contains "post_id":"<N>" in a JSON-ish JS blob.
• Recent posts: /post/recentposts returns only scaffolds (post_id + spinner); the browser lazy-loads each teaser via /members/postWidgetFill with post_id + caller. The recent_posts tool does this concurrently.

License

MIT (placeholder pending final decision).