From f14589f0095443f21170d54aedea24dc8128756a Mon Sep 17 00:00:00 2001 From: Torsten Mahr Date: Mon, 21 Sep 2026 21:22:52 +0200 Subject: [PATCH] docs: add agent working rules and Copilot app configuration Add a "Working in this repository" section to AGENTS.md with layout, the validation command, forbidden operations, credential handling and attribution, and point the GitHub Copilot app at it. Co-Authored-By: Claude Sonnet 5 Claude-Session: https://claude.ai/code/session_01CdiwBVuH6DCEtFPPwxbXKc --- .github/github-app.yml | 12 ++++++++++ AGENTS.md | 52 ++++++++++++++++++++++++++++++++++++++++++ 2 files changed, 64 insertions(+) create mode 100644 .github/github-app.yml diff --git a/.github/github-app.yml b/.github/github-app.yml new file mode 100644 index 0000000..0ce8494 --- /dev/null +++ b/.github/github-app.yml @@ -0,0 +1,12 @@ +# Repository configuration for the GitHub Copilot app. +# +# The authoritative instructions for this repository are in AGENTS.md. This file +# points at them rather than restating them, so the two cannot drift apart. + +instructions: | + Read AGENTS.md in the repository root and follow it, starting with the section + "Working in this repository". It is the authoritative guidance for this repository. + +scripts: + - name: Validate + command: ruff format --check . && ruff check . && mypy markitdown_mcp/ && pytest tests/unit/ diff --git a/AGENTS.md b/AGENTS.md index 1da8a3f..37b4ad1 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -2,6 +2,58 @@ This guide provides comprehensive information for AI agents and assistants on how to effectively use the MarkItDown MCP server for document conversion tasks. +## Working in this repository + +Read this section before changing anything here. The rest of this file is a usage guide for agents that call the +server; this section is for agents that change its code. + +### Layout + +| Path | Purpose | +|---|---| +| `markitdown_mcp/` | The server package: `server.py` holds the MCP tools and the `main` entry point | +| `tests/` | Unit, integration, security, performance and compatibility tests | +| `schemas/` | Generated tool schemas. Never hand-edit; regenerate with `python scripts/generate-schemas.py` | +| `docs/` | Guides and API documentation. `docs/api/generated/` is produced by the documentation workflow | +| `.github/workflows/` | CI, release and maintenance automation. See [`RELEASE.md`](RELEASE.md) for the release pipeline | + +### Validate before proposing a change + +Set up with `pip install -e ".[dev,test]"`, then run all of these; every one must pass: + +```sh +ruff format --check . && ruff check . && mypy markitdown_mcp/ +pytest tests/unit/ +``` + +The CI job `Unit Tests & Coverage` runs the same tests, and [`CONTRIBUTING.md`](CONTRIBUTING.md) describes the pull +request rules. Python 3.10 or later is required and is declared in `pyproject.toml`. + +### Do not do these + +- Do not rewrite history, force push, or delete branches. +- Do not commit secrets, tokens, or personal data. Push protection is enabled; a blocked push means stop and tell + the maintainer, not retry. +- Do not create or move tags, publish to PyPI, or run the release workflow. A release is made from a tag by the + pipeline described in [`RELEASE.md`](RELEASE.md), and the maintainer starts it. +- Do not change repository settings, branch protection, or the `pypi` environment. Those are maintainer actions. +- Do not hand-edit `schemas/*.json` or anything under `docs/api/generated/`; change the source and regenerate. +- Do not add a dependency without stating why in the pull request. +- The server reads and writes files on the user's machine. Do not add a code path that reads outside the paths the + caller supplies, and do not run `convert_directory` against a directory you were not asked to convert. + +### Credentials + +The repository holds no long-lived credential. Publishing to PyPI uses trusted publishing from the `pypi` +environment of `release.yml`, so there is no PyPI token to leak. If that trust is exposed, the maintainer removes +the publisher on pypi.org and re-adds it. The only other secrets are `GITHUB_TOKEN`, which GitHub issues per run, +and the optional `GITLEAKS_LICENSE`, which the maintainer replaces in the repository's secret settings. + +### Attribution + +Commits written by an agent carry a `Co-Authored-By` trailer naming the agent, and every change goes through a pull +request that a person can review. Nothing is pushed straight to `main`. + ## 🤖 Quick Reference for AI Agents ### Primary Use Cases