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

1. Repository Discovery

   • List repositories visible to bot user
   • Get repository metadata

2. File Operations

   • Get file tree for a repository
   • Read file contents (with size limits)

3. Commit History (Phase 4)

   • List commits for a repository
   • Get commit details and diffs

4. 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

1. Never expose the MCP server publicly — use a reverse proxy with TLS
2. Rotate bot tokens regularly
3. Monitor audit logs for unexpected access patterns
4. Keep Docker images updated
5. 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:

1. Maintain read-only guarantees
2. Add comprehensive audit logging for new tools
3. Include tests for authorization and boundary cases
4. 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.