<div align="center">

<img src="https://raw.githubusercontent.com/Devopstrio/.github/main/assets/Browser_logo.png" height="90"/>

<h1>mcp-registry</h1>

<p><strong>Centralized Model Context Protocol (MCP) Tool, Resource, & Prompt Registry</strong></p>

[![Build Status](https://img.shields.io/badge/Build-Passing-10B981?style=flat-square)](https://devopstrio.co.uk)
[![Python Version](https://img.shields.io/badge/Python-3.11%2B-3776AB.svg?style=flat-square)](https://python.org)
[![MCP Registry](https://img.shields.io/badge/MCP-Tool_Registry-8B5CF6?style=flat-square)](https://modelcontextprotocol.io)
[![Terraform](https://img.shields.io/badge/IaC-OpenTofu_1.8.5-FF5733?style=flat-square)](https://opentofu.org)

</div>

---

## Executive Summary

The **mcp-registry** repository provides a production-grade, centralized catalog and discovery registry for the Model Context Protocol (MCP). It indexes enterprise MCP tools, resources, and prompt templates with strict JSON schema validation and Role-Based Access Control (RBAC) filtering.

## Business Problem

As autonomous AI agents expand across an enterprise, discovering and governing available MCP tools faces operational challenges:
- **Shadow Tool Sprawl**: Unmonitored MCP tool servers registered directly by developers introduce unvetted execution endpoints.
- **Malformed Input Payloads**: Invalid tool argument schemas lead to runtime agent crashes and unhandled exceptions.
- **Unrestricted Access**: Lack of role-based tool discovery allows low-privilege agents to invoke sensitive administrative operations.

## Business Value

- **Centralized Governance Catalog**: Single source of truth for all approved MCP tools, resource URIs, and prompt templates across the organization.
- **Strict Schema Enforcement**: Validates JSON schema definitions during tool registration to prevent invalid parameter calls.
- **Role-Based Access Control (RBAC)**: Dynamically filters tool discovery queries based on the calling user or agent's authorized roles.

## Architecture

![Architecture Diagram](images/architecture.png)

### High-Level Execution Sequence

```mermaid
graph TD
    Client["AI Agent / Assistant Client"] --> RegistryAPI["MCP Registry REST API"]
    RegistryAPI --> CatalogService["Central Tool Catalog Service"]
    RegistryAPI --> SchemaValidator["JSON Schema Validator"]
    RegistryAPI --> PromptStore["Prompt Template Store"]
    CatalogService --> RBACFilter["Role-Based Access Control Filter"]
    RBACFilter --> FilteredTools["Accessible MCP Tools & Resources"]
```

## Core Components

- **Central Tool Catalog Service (`src/mcp_registry/core/catalog.py`)**: Core indexer storing tool definitions, server mappings, and role permissions.
- **JSON Schema Validator (`src/mcp_registry/validators/schema_validator.py`)**: Validates input schema definitions during tool registration.
- **Prompt Template Store (`src/mcp_registry/services/prompt_store.py`)**: Stores and serves standardized enterprise prompt templates.
- **FastAPI Async API Layer (`src/mcp_registry/api/routes.py`)**: REST endpoints for tool registration, RBAC filtering, and prompt listing.

## Repository Structure

```
mcp-registry/
├── .github/              # CI/CD workflows, issue & PR templates, CODEOWNERS
├── architecture/         # Mermaid sequence flow diagrams
├── deployment/           # Kubernetes manifests & Kustomize environment overlays
├── docs/                 # Enterprise architectural, deployment, & operational guides
├── examples/             # Real-world request/response JSON payloads
├── images/               # High-resolution architecture & workflow diagrams
├── src/mcp_registry/     # Python Registry source (api, core, services, validators)
├── terraform/            # Multi-cloud OpenTofu / Terraform IaC modules
├── tests/                # Unit, integration, and API test suites
├── Dockerfile            # Container build specification
├── docker-compose.yml    # Multi-container local orchestration
├── pyproject.toml        # PEP 621 package configuration
└── README.md             # Accelerator documentation manual
```

## Capabilities

- **Tool Registration & Discovery**: Endpoint for registering new MCP tools and discovering available schemas.
- **RBAC Tool Filtering**: Dynamic filtering based on caller role declarations.
- **Prompt Template Management**: Centralized repository for versioned prompt templates.
- **Multi-Cloud IaC Automation**: OpenTofu and Terraform modules for AWS VPC, IAM, ECS, and CloudWatch metrics.

## Technology Stack

- **Core Registry**: Python 3.11+, FastAPI 0.110+, Pydantic v2
- **Infrastructure as Code**: OpenTofu 1.8.5 / Terraform 1.6+
- **Containerization**: Docker, Docker Compose, Kubernetes 1.28+
- **Quality Assurance**: Pytest 8.0+, GitHub Actions CI

## Implementation

```bash
# Clone repository
git clone https://github.com/Devopstrio/mcp-registry.git
cd mcp-registry

# Install in editable mode
pip install -e .[dev]

# Run automated unit and integration tests
pytest -v tests/
```

## Deployment

### OpenTofu / Terraform Provisioning

```bash
cd terraform
tofu init
tofu plan
tofu apply -auto-approve
```

### Kubernetes Kustomize Deployment

```bash
kubectl apply -k deployment/kubernetes/overlays/prod/
```

## API Reference

- `GET /health` &mdash; Returns registry health status and version.
- `POST /api/v1/tools/register` &mdash; Registers an MCP tool with schema validation.
- `POST /api/v1/tools/filter` &mdash; Returns accessible tools based on RBAC user roles.
- `GET /api/v1/prompts` &mdash; Lists registered prompt templates.

## Examples

- [`examples/tool-registration/`](examples/tool-registration/) &mdash; MCP tool registration payload
- [`examples/prompt-template-store/`](examples/prompt-template-store/) &mdash; Prompt template listing payload
- [`examples/rbac-tool-filtering/`](examples/rbac-tool-filtering/) &mdash; RBAC tool filtering payload

## Security

Refer to [`SECURITY.md`](SECURITY.md) for reporting security vulnerabilities. The registry enforces schema validation and role-based access filtering.

## Observability

The platform exports structured CloudWatch log groups (`/aws/mcp-registry/mcp-registry`) and metric alarms for invalid schema registration attempts.

## Scalability

Horizontal pod autoscaling (HPA) overlays scale registry replicas dynamically based on query volume.

## Multi-cloud Strategy

Infrastructure blueprints support AWS ECS/VPC deployment with modular extensions for multi-cluster registry synchronization.

## Roadmap

See [`docs/Roadmap.md`](docs/Roadmap.md) for upcoming milestones including active MCP server health probing and semantic versioning support.

## Contribution

See [`CONTRIBUTING.md`](CONTRIBUTING.md) and [`CODE_OF_CONDUCT.md`](CODE_OF_CONDUCT.md) for community standards and contribution workflows.

---

<div align="center">
© 2026 Devopstrio — Engineering the Autonomous Enterprise.
</div>