Metadata-Version: 2.4
Name: airulermcp
Version: 0.3.0
Summary: MCP server for distributing AI rules from GitLab repositories to IDEs
Project-URL: Homepage, https://github.com/junqed/aimcp
Project-URL: Documentation, https://github.com/junqed/aimcp#readme
Project-URL: Repository, https://github.com/junqed/aimcp
Project-URL: Issues, https://github.com/junqed/aimcp/issues
Author-email: Lenny <rusts-talus-9g@icloud.com>
Maintainer-email: Lenny <rusts-talus-9g@icloud.com>
License: MIT
License-File: LICENSE
Keywords: ai,gitlab,ide,mcp,model-context-protocol,tools
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: MIT License
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.13
Classifier: Topic :: Software Development
Classifier: Topic :: Software Development :: Libraries :: Python Modules
Requires-Python: >=3.13
Requires-Dist: fastmcp>=2.0.0
Requires-Dist: httpx>=0.27.0
Requires-Dist: orjson>=3.11.3
Requires-Dist: pydantic-settings>=2.4.0
Requires-Dist: pydantic>=2.8.0
Requires-Dist: pyyaml>=6.0.0
Requires-Dist: structlog>=24.1.0
Requires-Dist: typer>=0.12.0
Description-Content-Type: text/markdown

# AIMCP

[![PyPI version](https://badge.fury.io/py/aimcp.svg)](https://badge.fury.io/py/aimcp)
[![Python 3.13+](https://img.shields.io/badge/python-3.13+-blue.svg)](https://www.python.org/downloads/)
[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)

AIMCP is an MCP (Model Context Protocol) server that enables teams to distribute MCP tool specifications from GitLab repositories to IDEs like Cursor and VS Code. The server discovers `tools.json` files in repositories, dynamically generates MCP tools from their specifications, and serves referenced files as resources through a secure URI scheme.

## Features

- **GitLab Integration**: Automatically discovers and fetches `tools.json` files from configured repositories
- **Dynamic Tool Generation**: Creates MCP tools from specifications at runtime
- **Secure Resource Access**: Serves repository files via `aimcp://` URI scheme with access control
- **Dual Caching**: Caches both tool specifications and file content for optimal performance
- **Conflict Resolution**: Handles duplicate tool names across repositories with configurable strategies
- **Async Architecture**: Built on `fastmcp` for high-performance async operations

## Installation

```bash
pip install aimcp
```

## Quick Start

1. Create a configuration file `config.yaml`:

```yaml
gitlab:
  base_url: "https://gitlab.example.com"
  token: "your-gitlab-token"
  repositories:
    - path: "team/tools-repo"
      branch: "main"

cache:
  type: "memory"
  ttl: 3600

conflict_resolution: "prefix"
```

2. Run the server:

```bash
aimcp
```

3. Connect your IDE to the MCP server at the configured endpoint.

## Tool Specifications

Each repository must contain a `tools.json` file following the [MCP specification](https://spec.modelcontextprotocol.io/). Example:

```json
{
  "tools": [
    {
      "name": "analyze_code",
      "description": "Analyze code quality and suggest improvements",
      "resourceRefs": ["analyzer_script", "analyzer_rules"]
      }
    }
  ],
  "resources": [
    {
      "name": "analyzer_script",
      "uri": "scripts/analyze.py",
    },
    {
      "name": "analyzer_rules",
      "uri": "configs/rules.yaml"
    }
  ]
}
```

## Configuration

### Conflict Resolution Strategies

- `prefix`: Add repository prefix to tool names (`repo1_toolname`, `repo2_toolname`)
- `priority`: First repository in configuration order wins
- `error`: Fail startup with detailed conflict report
- `merge`: Combine tool descriptions and resource lists

### Cache Options

- `memory`: In-memory caching (default)
- `redis`: Redis-backed caching for distributed setups (not implemented)

## Development

### Prerequisites

- Python 3.13+
- uv (recommended package manager)

### Setup

```bash
# Clone the repository
git clone https://github.com/yourusername/aimcp.git
cd aimcp

# Install dependencies
uv sync --dev

# Run tests
uv run pytest

# Run linting
uv run ruff check .

# Run type checking
uv run mypy .
```

## License

This project is licensed under the MIT License - see the [LICENSE](LICENSE) file for details.

## Contributing

Contributions are welcome! Please feel free to submit a Pull Request.

## Vibe coding product

Generated with Claude
