fds-mcp 0.1.0__tar.gz

fds_mcp-0.1.0/.github/workflows/ci.yml

@@ -0,0 +1,88 @@
+name: CI
+
+on:
+  push:
+    branches: [main]
+  pull_request:
+  workflow_dispatch:
+
+# Read-only, repository-wide. Deliberately NOT pull_request_target: this workflow
+# checks out and executes the contents of the pull request (pip install -e runs the
+# build backend), and pull_request_target would do that with a writable token and
+# access to repository secrets.
+permissions:
+  contents: read
+
+jobs:
+  test:
+    name: pytest (Python ${{ matrix.python-version }})
+    runs-on: ubuntu-latest
+    strategy:
+      fail-fast: false
+      matrix:
+        python-version: ["3.10", "3.11", "3.12"]
+
+    steps:
+      - uses: actions/checkout@v5
+        with:
+          persist-credentials: false
+
+      - uses: actions/setup-python@v5
+        with:
+          python-version: ${{ matrix.python-version }}
+          cache: pip
+
+      - name: Install
+        run: |
+          python -m pip install --upgrade pip
+          pip install -e ".[dev]"
+
+      - name: Lint
+        run: python -m ruff check src tests
+
+      - name: Run the offline test suite
+        run: python -m pytest -m "not live" -v
+
+  secrets:
+    name: secret scan
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v5
+        with:
+          fetch-depth: 0          # gitleaks scans every commit, not just the tip
+          persist-credentials: false
+
+      - name: Install gitleaks
+        env:
+          GITLEAKS_VERSION: 8.28.0
+          GITLEAKS_SHA256: a65b5253807a68ac0cafa4414031fd740aeb55f54fb7e55f386acb52e6a840eb
+        run: |
+          set -euo pipefail
+          curl -sSfL -o gitleaks.tar.gz \
+            "https://github.com/gitleaks/gitleaks/releases/download/v${GITLEAKS_VERSION}/gitleaks_${GITLEAKS_VERSION}_linux_x64.tar.gz"
+          echo "${GITLEAKS_SHA256}  gitleaks.tar.gz" | sha256sum -c -
+          tar -xzf gitleaks.tar.gz gitleaks
+          ./gitleaks version
+
+      - name: Scan the whole git history
+        run: ./gitleaks git --redact --verbose --exit-code 1 .
+
+      - name: Scan the working tree
+        run: ./gitleaks dir --redact --verbose --exit-code 1 .
+
+      - name: Check that no secret-bearing file is tracked
+        run: |
+          if git ls-files | grep -E '(^|/)(tokens\.json|config\.json|\.env)$|\.(pem|key|p12|pfx)$'; then
+            echo "::error::A secret-bearing file is tracked in git."
+            exit 1
+          fi
+
+      - name: Check for private network addresses and internal hostnames
+        run: |
+          set -euo pipefail
+          pattern='(^|[^0-9.])(10\.[0-9]{1,3}\.[0-9]{1,3}\.[0-9]{1,3}|192\.168\.[0-9]{1,3}\.[0-9]{1,3}|172\.(1[6-9]|2[0-9]|3[01])\.[0-9]{1,3}\.[0-9]{1,3}|100\.(6[4-9]|[7-9][0-9]|1[01][0-9]|12[0-7])\.[0-9]{1,3}\.[0-9]{1,3})|\.intranet\.|\.internal\b|\.ts\.net\b'
+          # The workflow file is excluded because it contains the pattern itself.
+          if git grep -nEI "$pattern" -- . ':!*.png' ':!*.jpg' ':!.github/workflows/ci.yml'; then
+            echo "::error::An internal address or hostname reached the repository."
+            exit 1
+          fi

fds_mcp-0.1.0/.github/workflows/release.yml

@@ -0,0 +1,64 @@
+# Publishes to PyPI when a v* tag is pushed.
+#
+# No API token anywhere: PyPI's Trusted Publishing exchanges the workflow's OIDC
+# identity for a short-lived upload credential. That is why `id-token: write` and the
+# `pypi` environment below have to match the publisher configured on PyPI exactly.
+name: Release
+
+on:
+  push:
+    tags: ["v*"]
+
+permissions:
+  contents: read
+
+jobs:
+  build:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v5
+
+      - uses: actions/setup-python@v5
+        with:
+          python-version: "3.12"
+
+      - name: Refuse to release a tag that disagrees with the package version
+        run: |
+          set -euo pipefail
+          tag="${GITHUB_REF_NAME#v}"
+          pkg=$(python -c "import tomllib,pathlib; \
+            print(tomllib.loads(pathlib.Path('pyproject.toml').read_text())['project']['version'])")
+          echo "tag=$tag pyproject=$pkg"
+          [ "$tag" = "$pkg" ] || { echo "::error::tag $tag != version $pkg"; exit 1; }
+
+      - name: Install and test before anything is published
+        run: |
+          python -m pip install --upgrade pip
+          pip install -e ".[dev]" build
+          python -m pytest -m "not live" -q
+
+      - run: python -m build
+
+      - name: Check the artifacts render on PyPI
+        run: |
+          pip install twine
+          python -m twine check dist/*
+
+      - uses: actions/upload-artifact@v4
+        with:
+          name: dist
+          path: dist/
+
+  publish:
+    needs: build
+    runs-on: ubuntu-latest
+    environment: pypi
+    permissions:
+      id-token: write        # the whole point: no stored credential
+    steps:
+      - uses: actions/download-artifact@v4
+        with:
+          name: dist
+          path: dist/
+
+      - uses: pypa/gh-action-pypi-publish@release/v1

fds_mcp-0.1.0/.gitignore

@@ -0,0 +1,59 @@
+# --- secrets: never commit ---
+tokens.json
+config.json
+.env
+.env.*
+*.pem
+*.key
+*.p12
+*.pfx
+secrets/
+
+# --- Python ---
+__pycache__/
+*.py[cod]
+*$py.class
+*.so
+.Python
+build/
+develop-eggs/
+dist/
+downloads/
+eggs/
+.eggs/
+lib64/
+parts/
+sdist/
+var/
+wheels/
+share/python-wheels/
+*.egg-info/
+.installed.cfg
+*.egg
+MANIFEST
+
+# --- virtualenvs ---
+.venv/
+venv/
+ENV/
+env/
+
+# --- test / tooling ---
+.pytest_cache/
+.mypy_cache/
+.ruff_cache/
+.coverage
+.coverage.*
+htmlcov/
+coverage.xml
+.tox/
+.nox/
+
+# --- editors / OS ---
+.idea/
+.vscode/
+.DS_Store
+
+# --- local working data ---
+drafts/
+*.body.txt

fds_mcp-0.1.0/CHANGELOG.md

@@ -0,0 +1,78 @@
+# Changelog
+
+All notable changes to this project are documented here. The format follows
+[Keep a Changelog](https://keepachangelog.com/en/1.1.0/), and this project adheres to
+[Semantic Versioning](https://semver.org/spec/v2.0.0.html).
+
+## [Unreleased]
+
+### Added
+
+- **`build_reply_draft`** (yellow): prepares a follow-up message to an authority — looks
+  the request up, validates the text, and returns the finished message, the subject in
+  froide's own format (`AW: <title> [#<id>]`) and the URL of the form. It sends nothing,
+  and there is no argument that makes it.
+- **Rule `R19-reply-needs-salutation`**, the inverse of `R10`. froide does not frame a
+  follow-up, so salutation and closing formula have to stand in the text, exactly once
+  each. The reply rule set also applies `R04` (the form is prefilled with U+2026), `R06`
+  and the 230-character subject cap.
+- **Rules `R18-full-text-self-contained` and `L06-required-elements`**, which check the
+  letter the authority *receives* rather than the body that was written: legal basis (the
+  only `ERROR`), cost pre-notification, cost cap, deadline, forwarding when not
+  responsible, electronic reply.
+- **`send_reply_via_browser`** (red, opt-in): sends an approved reply draft by driving a
+  real browser. Not registered unless `FDS_MCP_BROWSER_SEND=1`; needs the optional extra
+  `fds-mcp[browser]`. Five gates plus in-form checks, and an API confirmation afterwards —
+  without it the outcome is reported as `unconfirmed`, never as success. The README states
+  plainly what switching it on costs.
+- **`tests/test_api_contract.py`**: live learning tests that fire when FragDenStaat changes
+  the limits this server is built around — the `kind: "email"` refusal with its
+  `kind: "post"` calibration, the web view's indifference to bearer tokens, and the set of
+  resources the API router exposes.
+- **German documentation** alongside the English original: `README.de.md` and
+  `docs/oauth-setup.de.md`, linked in both directions. US English is the source.
+- Environment variables `FDS_MCP_BROWSER_SEND` and `FDS_MCP_BROWSER_PROFILE`.
+
+## [0.1.0] — 2026-09-05
+
+First release.
+
+### Added
+
+- **MCP stdio server** (`fds-mcp serve`) exposing 14 tools in three safety tiers.
+- **Green tools** (no authentication, no side effects): `search_authorities`,
+  `get_authority`, `get_law`, `check_jurisdiction`.
+  - `get_authority` recomputes the law that the REST API would apply, because the API
+    does not expose `default_law`.
+  - `check_jurisdiction` walks the GeoRegion `part_of` chain and returns the evidence
+    trail alongside the covering authorities.
+- **Yellow tools** (OAuth token, read only): `list_my_requests`, `get_request`,
+  `get_messages`, `list_attachments`, `download_attachment`, `check_deadlines`.
+- **Red tools** (`dry_run=True` by default): `create_request_draft` (local YAML only, no
+  network), `validate_draft`, `build_submit_url` (two-step above the measured 4096-byte
+  URL limit), `submit_request`.
+- **Five submission gates** enforced in code: approved status, no open ERROR finding,
+  desired law equal to the API default, a human-set confirmation token, and local
+  rate-limit bookkeeping against 5/5min, 6/6h, 10/24h and 20/7d.
+- **Read-only HTTP client**: every non-GET method is refused unless `allow_write=True`
+  is set explicitly. Pagination de-duplicates by id and raises rather than truncating
+  silently.
+- **OAuth 2.0 Authorization Code + PKCE** (`fds-mcp login`) with an HTTPS loopback
+  listener on `https://localhost:8765/callback` and a `fragdenstaat://callback` fallback
+  for manual paste. Tokens are stored at `~/.config/fds-mcp/tokens.json` with mode 0600
+  and refreshed automatically.
+- **Rule set** `R01`–`R17` offline and `L01`–`L05` live, reproducing froide's web-form
+  validation, which is considerably stricter than the REST API's.
+- CLI subcommands `serve`, `configure`, `login`, `whoami`, `status`, `logout`,
+  `validate`.
+- Test suite with `pytest-socket`; network access is blocked except for tests marked
+  `live`, which perform read-only GETs.
+
+### Known limitations
+
+Not offered, because the API does not support it: replying to an authority by e-mail,
+choosing the legal basis via `POST /api/v1/request/`, server-side drafts, and setting
+status, resolution, tags or the law after the fact. Documenting postal mail (tus upload
+plus `kind: post`) is possible through the API but is not implemented yet.
+
+[0.1.0]: https://github.com/notDIRK/fds-mcp/releases/tag/v0.1.0

fds_mcp-0.1.0/CONTRIBUTING.md

@@ -0,0 +1,59 @@
+# Contributing
+
+Thanks for taking a look.
+
+## Ground rules
+
+1. **Never invent an endpoint or a field.** Every claim about the FragDenStaat API must
+   be verifiable — against the live site, against the OpenAPI schema at
+   `https://fragdenstaat.de/api/v1/schema/`, or against a specific place in
+   [okfde/froide](https://github.com/okfde/froide) /
+   [okfde/fragdenstaat_de](https://github.com/okfde/fragdenstaat_de). Cite it in a
+   comment or a docstring.
+2. **Never send a write to fragdenstaat.de while developing or testing.** No POST, PUT,
+   PATCH or DELETE, not even once, not even "just to see". Tests that touch the network
+   are marked `live` and perform read-only GETs.
+3. **Do not weaken the safety gates.** The seven rules in the README's *Safety model* are
+   the point of this project. If you change one, the test that proves it has to change
+   with it, and the reasoning belongs in the pull request.
+4. **No secrets in the repository.** Not in code, not in examples, not in test fixtures,
+   not in commit messages. `.gitignore` covers `tokens.json`, `config.json`, `.env`,
+   `*.pem` and `*.key`; do not work around it.
+
+## Setup
+
+```bash
+python -m venv .venv && source .venv/bin/activate
+pip install -e ".[dev]"
+python -m pytest -m "not live"
+```
+
+`python -m pytest -m "not live"` must be green before you open a pull request. Run
+`python -m pytest -m live` too if your change touches the API layer.
+
+## Adding a rule
+
+Rules live in `src/fds_mcp/rules.py`. Offline rules (`R…`) get `@offline_rule("Rnn-name")`
+and take the draft dict; live rules (`L…`) get `@live_rule("Lnn-name")` and additionally
+take a client. Use the next free number, do not renumber existing rules, and add a test
+that makes the rule fire on a deliberately broken draft.
+
+Pick the severity honestly:
+
+- `ERROR` — froide would reject this, or it would produce a wrong or harmful request.
+- `WARN` — likely a mistake, but a human might have meant it.
+- `INFO` — worth knowing.
+
+Only `ERROR` blocks a submission.
+
+## Style
+
+- Python 3.10+, type hints on public functions.
+- Comments explain *why*, especially where froide's behaviour is surprising.
+- Keep the docstring of every MCP tool accurate: it is the only thing the model reads.
+
+## Reporting a security issue
+
+Open a normal issue if it concerns the safety gates. If you have found something that
+could cause a request to be sent without a human's consent, please say so plainly in the
+title so it gets read first.

fds_mcp-0.1.0/Dockerfile

@@ -0,0 +1,34 @@
+# Runs the MCP server over stdio in a container.
+#
+# It exists mostly so directories such as Glama can start the server and read its tool
+# list. That works with no credentials at all: the four account-free tools are enough to
+# answer an introspection request.
+#
+#   docker build -t fds-mcp .
+#   docker run --rm -i fds-mcp
+#
+# To use the token-bound tools, mount the config directory read-only:
+#
+#   docker run --rm -i -v "$HOME/.config/fds-mcp:/config:ro" -e FDS_MCP_HOME=/config fds-mcp
+#
+# Nothing is written inside the container; drafts belong on the host.
+
+FROM python:3.12-slim
+
+# No .pyc, unbuffered stdio -- the transport is stdout, so buffering would stall it.
+ENV PYTHONDONTWRITEBYTECODE=1 \
+    PYTHONUNBUFFERED=1
+
+WORKDIR /app
+
+COPY pyproject.toml README.md LICENSE ./
+COPY src ./src
+
+RUN pip install --no-cache-dir .
+
+# Never as root: this process talks to a public API and writes local files.
+RUN useradd --create-home --uid 10001 fds
+USER fds
+
+# stdio transport: no port, no healthcheck, the client owns the lifecycle.
+ENTRYPOINT ["fds-mcp", "serve"]

fds_mcp-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Dirk Wolbeck
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.