Skip to content

AGENTS.md

Latest commit

 

History

History
129 lines (99 loc) · 5.14 KB

AGENTS.md

File metadata and controls

129 lines (99 loc) · 5.14 KB
Raw

AGENTS.md

Instructions for coding agents in this repository.

vocagateway-mcp is a thin MCP client for a user-operated VocaGateway. It does not perform speech inference itself. The current milestone is a local stdio server that reports gateway status, lists models, and sends a completed local audio file to the explicitly configured gateway. There is no Voca-hosted relay, account, or cloud transcription service.

Critical: git worktrees for every branch and PR

Never create a branch, commit, or open a pull request in the primary checkout. Use a linked git worktree so the primary checkout stays on main and clean.

git fetch origin
git worktree add /tmp/vocagateway-mcp-<task> -b <type>/<short-name> origin/main

# Edit, test, commit, push, and open the PR inside that worktree.

git worktree remove /tmp/vocagateway-mcp-<task>
git worktree prune

Rules:

  • One worktree per branch and one logical change per PR.
  • Put worktrees outside the primary checkout.
  • Never commit or push directly to main.
  • Never merge a PR; wait for maintainer review.
  • Clean up the worktree after the branch is published.

Layout

Path Role
src/vocagateway_mcp/client.py Configuration, HTTP client, destination confirmation, safe errors
src/vocagateway_mcp/server.py FastMCP tools and stdio entry point
tests/ Unit tests using httpx.MockTransport; no live gateway required
scripts/inspect-local.sh Local MCP Inspector launcher using the gateway token file
scripts/smoke_stdio.py Installed-wheel MCP initialize and tool-list smoke test
Dockerfile Stdio container image
.github/workflows/quality.yml Python/package/protocol and container CI gates

Setup and commands

Python 3.12+ and uv are required. uv.lock is authoritative and must be committed whenever dependencies change.

uv sync --locked --all-groups
uv run ruff check .
uv run ruff format --check .
uv run pytest

uv build --wheel
uv run python scripts/smoke_stdio.py .venv/bin/vocagateway-mcp
docker build --tag vocagateway-mcp:test .

Use uv run ruff format . and uv run ruff check --fix . for mechanical fixes. Run git diff --check before committing.

Architecture and API contract

  • Keep gateway-independent logic in GatewayClient; MCP tools should be thin adapters so a future Streamable HTTP transport can reuse the same client.
  • GatewayClient owns one reusable httpx.AsyncClient; route gateway calls through its unified request helper and close it through the MCP lifespan.
  • Stdio is the only supported MCP transport in the current milestone.
  • get_gateway_status uses public gateway health endpoints.
  • list_models is read-only but uses the configured gateway bearer token.
  • transcribe_file uses POST /v1/audio/transcriptions and must require the caller to confirm the normalized gateway URL before the file is opened.
  • Do not add streaming transcription, token administration, model mutations, arbitrary URL ingestion, or a hosted Voca relay without an explicit product decision.
  • Coordinate changes to gateway paths or response shapes with VocaHQ/vocagateway; do not silently invent compatibility behavior.

Privacy and security

Never commit or log:

  • Bearer tokens or token files
  • Audio recordings or transcripts, including test fixtures
  • Personal gateway URLs, LAN addresses, or tailnet hostnames
  • .env files, diagnostics containing secrets, or local application data

Tests must use generated bytes, synthetic metadata, and reserved example hosts. Do not echo gateway response bodies in errors because they may contain secrets or transcripts. Do not weaken destination confirmation, bearer authentication, timeouts, upload controls, or error redaction without explicit review.

Local file access must remain bounded to the path the caller supplied. Hosted transport work must define a remote-safe audio input contract; a path on the MCP server is not the remote user's local file.

Python conventions and tests

  • Use from __future__ import annotations.
  • Ruff targets Python 3.12 with line length 100.
  • Prefer explicit types, small async methods, specific exceptions, and early validation before file or network access.
  • Tests live in tests/test_*.py; use pytest and httpx.MockTransport.
  • Unit tests must not require VocaGateway, VocaMac, a speech model, Docker, or network access.
  • Every new tool needs schema/registration coverage and success, validation, authentication, and secret-redaction tests where applicable.
  • Keep stdout reserved for MCP JSON-RPC; diagnostics belong on stderr.

CI, commits, and pull requests

quality.yml runs on pushes to main, non-draft PRs, and manual dispatch. It checks the lockfile, Ruff, pytest, a clean wheel install, an MCP stdio handshake, and the Docker build.

Use Conventional Commits: feat, fix, docs, test, ci, refactor, build, or chore. PR descriptions should include:

  • Summary and rationale
  • Exact verification commands and results
  • Privacy/security impact
  • Any live-gateway or container testing performed

Update this file when commands, layout, supported transports, or agent rules change.