AegisGitea MCP
A private, security-first MCP server for controlled AI access to self-hosted Gitea
Overview
AegisGitea MCP is a Model Context Protocol (MCP) server that enables controlled, auditable, read-only AI access to a self-hosted Gitea environment.
The system allows ChatGPT (Business / Developer environment) to inspect repositories, code, commits, issues, and pull requests only through explicit MCP tool calls, while all access control is dynamically managed through a dedicated bot user inside Gitea itself.
Core Principles
- Strong separation of concerns: Clear boundaries between AI, MCP server, and Gitea
- Least-privilege access: Bot user has minimal necessary permissions
- Full auditability: Every AI action is logged with context
- Dynamic authorization: Access control via Gitea permissions (no redeployment needed)
- Privacy-first: Designed for homelab and private infrastructure
Architecture
┌─────────────────────────────────────────────────────────────┐
│ ChatGPT (Business/Developer) │
│ - Initiates explicit MCP tool calls │
│ - Human-in-the-loop decision making │
└────────────────────┬────────────────────────────────────────┘
│ HTTPS (MCP over SSE)
▼
┌─────────────────────────────────────────────────────────────┐
│ AegisGitea MCP Server (Python, Docker) │
│ - Implements MCP protocol │
│ - Translates tool calls → Gitea API requests │
│ - Enforces access, logging, and safety constraints │
│ - Provides bounded, single-purpose tools │
└────────────────────┬────────────────────────────────────────┘
│ Gitea API (Bot User Token)
▼
┌─────────────────────────────────────────────────────────────┐
│ Gitea Instance (Docker) │
│ - Source of truth for authorization │
│ - Hosts dedicated read-only bot user │
│ - Determines AI-visible repositories dynamically │
└─────────────────────────────────────────────────────────────┘
Trust Model
| Component | Responsibility |
|---|---|
| Gitea | Authorization (what the AI can see) |
| MCP Server | Policy enforcement (how the AI accesses data) |
| ChatGPT | Decision initiation (when the AI acts) |
| Human | Final decision authority (why the AI acts) |
Features
Phase 1 — Foundation (Current)
- MCP protocol handling with SSE lifecycle
- Secure Gitea API communication via bot user token
- Health and readiness endpoints
- ChatGPT MCP registration flow
Phase 2 — Authorization & Data Access (Planned)
- Repository discovery based on bot user permissions
- File tree and content retrieval with size limits
- Dynamic access control (changes in Gitea apply instantly)
Phase 3 — Audit & Hardening (Planned)
- Comprehensive audit logging (timestamp, tool, repo, path, correlation ID)
- Request correlation and tracing
- Input validation and rate limiting
- Defensive bounds on all operations
Phase 4 — Extended Context (Future)
- Commit history and diff inspection
- Issue and pull request visibility
- Full contextual understanding while maintaining read-only guarantees
Authorization Model
Bot User Strategy
A dedicated Gitea bot user represents "the AI":
- The MCP server authenticates as this user using a read-only token
- The bot user's repository permissions define AI visibility
- No admin privileges
- No write permissions
- No implicit access
This allows dynamic enable/disable of AI access without restarting or reconfiguring the MCP server.
Example:
# Grant AI access to a repository
git clone https://gitea.example.com/org/repo.git
cd repo
# Add bot user as collaborator with Read permission in Gitea UI
# Revoke AI access
# Remove bot user from repository in Gitea UI
MCP Tool Design
All tools are:
- Explicit: Single-purpose, no hidden behavior
- Deterministic: Same input always produces same output
- Bounded: Size limits, path constraints, no wildcards
- Auditable: Full logging of every invocation
Tool Categories
-
Repository Discovery
- List repositories visible to bot user
- Get repository metadata
-
File Operations
- Get file tree for a repository
- Read file contents (with size limits)
-
Commit History (Phase 4)
- List commits for a repository
- Get commit details and diffs
-
Issues & PRs (Phase 4)
- List issues and pull requests
- Read issue/PR details and comments
Explicit Constraints
- No wildcard search tools
- No full-text indexing
- No recursive "read everything" operations
- No hidden or implicit data access
Audit & Observability
Every MCP tool invocation logs:
- Timestamp (UTC)
- Tool name
- Repository identifier
- Target (path / commit / issue)
- Correlation ID
Logs are:
- Append-only
- Human-readable JSON
- Machine-parseable
- Stored locally by default
Audit Philosophy: The system must answer "What exactly did the AI see, and when?" without ambiguity.
Deployment
Prerequisites
- Docker and Docker Compose
- Self-hosted Gitea instance
- Gitea bot user with read-only access token
Quick Start
# Clone repository
git clone https://gitea.example.com/your-org/AegisGitea-MCP.git
cd AegisGitea-MCP
# Configure environment
cp .env.example .env
# Edit .env with your Gitea URL and bot token
# Start MCP server
docker-compose up -d
# Check logs
docker-compose logs -f aegis-mcp
Environment Variables
| Variable | Description | Required |
|---|---|---|
GITEA_URL |
Base URL of Gitea instance | Yes |
GITEA_TOKEN |
Bot user access token | Yes |
MCP_HOST |
MCP server listen host | No (default: 0.0.0.0) |
MCP_PORT |
MCP server listen port | No (default: 8080) |
LOG_LEVEL |
Logging verbosity | No (default: INFO) |
AUDIT_LOG_PATH |
Audit log file path | No (default: /var/log/aegis-mcp/audit.log) |
Security Considerations
- Never expose the MCP server publicly — use a reverse proxy with TLS
- Rotate bot tokens regularly
- Monitor audit logs for unexpected access patterns
- Keep Docker images updated
- Use a dedicated bot user — never use a personal account token
Development
Setup
# Create virtual environment
python3 -m venv venv
source venv/bin/activate
# Install dependencies
pip install -r requirements-dev.txt
# Run tests
pytest tests/
# Run server locally
python -m aegis_gitea_mcp.server
Project Structure
AegisGitea-MCP/
├── src/
│ └── aegis_gitea_mcp/
│ ├── __init__.py
│ ├── server.py # MCP server entry point
│ ├── mcp_protocol.py # MCP protocol implementation
│ ├── gitea_client.py # Gitea API client
│ ├── audit.py # Audit logging
│ ├── config.py # Configuration management
│ └── tools/ # MCP tool implementations
│ ├── __init__.py
│ ├── repository.py # Repository discovery tools
│ └── files.py # File access tools
├── tests/
│ ├── test_mcp_protocol.py
│ ├── test_gitea_client.py
│ └── test_tools.py
├── docker/
│ ├── Dockerfile
│ └── docker-compose.yml
├── .env.example
├── pyproject.toml
├── requirements.txt
├── requirements-dev.txt
└── README.md
Non-Goals
Explicitly out of scope:
- No write access to Gitea (no commits, comments, merges, edits)
- No autonomous or background scanning
- No global search or unrestricted crawling
- No public exposure of repositories or credentials
- No coupling to GitHub or external VCS platforms
Roadmap
- Project initialization and architecture design
- Phase 1: MCP server foundation and Gitea integration
- Phase 2: Repository discovery and file access tools
- Phase 3: Audit logging and security hardening
- Phase 4: Commit history, issues, and PR support
Contributing
This project prioritizes security and privacy. Contributions should:
- Maintain read-only guarantees
- Add comprehensive audit logging for new tools
- Include tests for authorization and boundary cases
- Document security implications
License
MIT License - See LICENSE file for details
Acknowledgments
Built on the Model Context Protocol by Anthropic.
Support
For issues, questions, or security concerns, please open an issue in the Gitea repository.
Remember: This is designed to be boring, predictable, and safe — not clever, not magical, and not autonomous.