mcp-github-projects: Instructions file for Codex

AGENTS.md

Vendor-neutral guide for AI coding agents (and humans) working in this repository. This file is the single source of truth for how to build, test, extend, and contribute to the project. If an MCP client needs its own pointer file (for example .cursor/rules/*.mdc or .github/copilot-instructions.md), it must only point here — when they disagree, AGENTS.md wins. This repository intentionally does not create or maintain CLAUDE.md.

1. Project Overview

This repository is a Model Context Protocol (MCP) server for GitHub Projects V2. It exposes 100+ tools for managing issues, project-board fields, milestones, labels, sub-issues, sprints, epics, and PR/issue lifecycle automation. It is built on FastMCP, communicates over the stdio transport, and runs as a Docker container.

• Language: Python 3.12+, fully type-hinted.
• Transport: FastMCP over stdio (server.py → mcp.run(transport="stdio")).
• Data access: GitHub GraphQL API v4 (Projects V2) with a gh CLI fallback for REST-only operations.
• Runtime: Docker only — there are no supported host-Python workflows.
• Maintainership: single maintainer, public OSS (MIT).

2. Flat Repository Layout

The project uses a flat package layout (no nested src/ or vendor prefix). Imports are top-level (from tools.close import close_issue, from models.responses import ToolSuccess).

.
├── server.py            # FastMCP entry point; registers every tool
├── config.py            # Settings (env-driven): org/repo/project, timeouts, scopes
├── auth.py              # Token resolution + scope validation
├── capabilities.py      # Capability enum + profile capability enforcement
├── profiles.py          # Multi-target profile registry (user vs org projects)
├── error_handling.py    # build_error_response(), handle_tool_error()
├── exceptions.py        # Typed exceptions
├── hardening.py         # Input/rate-limit hardening helpers
├── tools/               # One module per tool (or tool family) — see §4
│   ├── __init__.py      # Re-exports the core tool subset
│   ├── comment_issue.py # Canonical single-tool example
│   ├── capability_suite.py  # Extended 60-tool suite (dynamic registration)
│   └── ...
├── services/            # Domain services (issue_service, project_service, ...)
├── clients/             # graphql_client, gh_cli_client, cache_manager
├── graphql/             # queries.py, mutations.py (GraphQL documents)
├── models/              # Pydantic models — responses.py, context.py, items.py
├── scripts/             # Docker-invoked CI/validation scripts (Python + bash)
├── tests/               # pytest suite
├── docs/                # SETUP, USAGE, PARAMETERS, CAPABILITIES, TROUBLESHOOTING
├── compose.yaml         # Single `mcp` service
├── Dockerfile
└── Makefile             # The ONLY supported command surface (Docker-backed)