Metadata-Version: 2.4
Name: mcp-service-registry
Version: 0.3.0
Summary: Multi-tenant MCP server that shares microservice API contracts between AI coding assistants
Project-URL: Homepage, https://github.com/sinan-mohammed/his-service-registry
Author-email: Sinan <sinan@curanova.ai>
License: MIT
License-File: LICENSE
Keywords: api-registry,claude,mcp,microservices,model-context-protocol
Classifier: Development Status :: 3 - Alpha
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: MIT License
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Topic :: Software Development :: Libraries
Requires-Python: >=3.10
Requires-Dist: httpx>=0.27
Requires-Dist: mcp[cli]>=1.2.0
Requires-Dist: psycopg[binary]>=3.1
Requires-Dist: uvicorn>=0.30
Description-Content-Type: text/markdown

# mcp-service-registry

An **MCP server** that lets multiple AI coding assistants (Claude Code, Cursor,
etc.) share microservice **API contracts**. A developer working on one service
can look up another service's real endpoints and field names — instead of
guessing and creating mismatched integrations.

> Example: "Billing" needs to call "Inventory". Instead of inventing field
> names, Billing's AI asks the registry and gets the exact Stock Request
> contract (`itemId`, `quantity`, `warehouseId`, `requestedBy`).

---

## Which user are you?

| I want to... | Do this |
|--------------|---------|
| **Look up other services' APIs** (most people) | [Connect to a running registry](#a-connect-to-a-running-registry-no-install) — just a URL, no install |
| **Run my own registry** (host it) | [Self-host](#b-run-your-own-registry) — install + database |

---

## A. Connect to a running registry (no install)

If your team already has a registry running (for example on Render), you only
need its URL. Nothing to install.

**Claude Code:**
```bash
claude mcp add --transport http registry https://YOUR-REGISTRY-URL/mcp
```

Or add it manually to your MCP config:
```json
{
  "mcpServers": {
    "registry": {
      "type": "http",
      "url": "https://YOUR-REGISTRY-URL/mcp"
    }
  }
}
```

**Then just ask your assistant, for example:**
- "Using the registry, what services exist?"
- "What fields does the inventory stock-request API need?"
- "Register this service's API in the registry."

That's it — the assistant will call the tools automatically.

---

## B. Run your own registry

### 1. Install
```bash
pip install mcp-service-registry
# or, to run without installing permanently:
uvx mcp-service-registry
```

### 2. Provide a PostgreSQL database
The server needs a PostgreSQL database. Point it at one with the
`REGISTRY_DB_URL` environment variable:
```bash
export REGISTRY_DB_URL="postgresql://user:pass@host:5432/dbname"
```

Create the table once:
```sql
CREATE TABLE IF NOT EXISTS services (
  name        TEXT PRIMARY KEY,
  description TEXT NOT NULL,
  contract    JSONB NOT NULL,
  updated_at  TIMESTAMPTZ NOT NULL DEFAULT now()
);
```

> Tip: a free cloud PostgreSQL (e.g. Neon) works well. On Windows + local
> Docker, use `127.0.0.1` instead of `localhost` in the URL.

### 3. Run it

**Local mode (stdio)** — for a single machine / testing / the Inspector:
```bash
mcp-registry
```
Add it to Claude Code as a local command:
```json
{
  "mcpServers": {
    "registry": {
      "command": "mcp-registry",
      "env": { "REGISTRY_DB_URL": "postgresql://..." }
    }
  }
}
```

**Network mode (HTTP)** — to share it with other devices:
```bash
export MCP_TRANSPORT=http
export MCP_PORT=8000          # optional; cloud hosts set PORT automatically
mcp-registry
```
It serves at `http://<this-machine>:8000/mcp`, with a health check at `/health`.

---

## The tools

| Tool | What it does | Arguments |
|------|--------------|-----------|
| `list_services` | List all registered services + descriptions | none |
| `get_service_api` | Get one service's endpoints, request fields, response fields | `service` |
| `add_service` | Add or update a service's API contract | `name`, `description`, `endpoints_json` |

### Registering a service

`add_service` takes the service name, a one-line description, and a JSON array
of endpoints. Each endpoint looks like:

```json
[
  {
    "method": "POST",
    "path": "/stock-request",
    "summary": "Create a stock request",
    "request_fields": {
      "itemId": "string (required)",
      "quantity": "integer (required, > 0)",
      "warehouseId": "string (required)",
      "requestedBy": "string (required)"
    },
    "response_fields": {
      "requestId": "string",
      "status": "string (PENDING | APPROVED | REJECTED)"
    }
  }
]
```

The easiest way to register: just ask your AI assistant, e.g.
*"Register the inventory service in the registry with a POST /stock-request
endpoint that takes itemId, quantity, warehouseId, requestedBy."* — it will
call `add_service` for you.

---

## Testing locally with the MCP Inspector
```bash
uvx --with mcp-service-registry mcp dev -c "from service_registry.server import mcp"
```
(Or clone the repo and run `uv run mcp dev src/service_registry/server.py`.)

---

## Configuration reference

| Variable | Default | Meaning |
|----------|---------|---------|
| `REGISTRY_DB_URL` | local Docker URL | PostgreSQL connection string |
| `MCP_TRANSPORT` | `stdio` | `stdio` (local) or `http` (network) |
| `MCP_PORT` / `PORT` | `8000` | Port for HTTP mode |

---

## Works with other assistants
Because it uses the open **Model Context Protocol**, it isn't limited to Claude
Code — any MCP-compatible client (Cursor, and others) can connect the same way.

## License
MIT
