# @erickwendel/ew-customers-mcp

An [MCP (Model Context Protocol)](https://modelcontextprotocol.io) server that exposes a legacy customer CRUD REST API as tools, a resource, and a prompt — all runnable directly inside VS Code Copilot Chat.

This server is a thin adapter: it wraps the legacy `nodejs-fastify-mongodb-crud` API (Node/Fastify + MongoDB) over HTTP and does not modify it. The legacy API stays exactly as it is; only the MCP wrapper was ported from TypeScript to Python.

---

## What it does

| Capability | Name | Description |
|---|---|---|
| 🔧 Tool | `list_customers` | Lists all customers |
| 🔧 Tool | `get_customer` | Finds a customer by id, name, or phone |
| 🔧 Tool | `create_customer` | Creates a customer |
| 🔧 Tool | `update_customer` | Updates a customer's name and/or phone by id |
| 🔧 Tool | `delete_customer` | Deletes a customer by id |
| 📄 Resource | `customers://api-info` | Describes the legacy REST API this server wraps |
| 💬 Prompt | `find_customer_prompt` | Pre-built prompt that asks the agent to search a customer |

---

## Architecture

```
src/customers_mcp/
  domain/
    customer.py          # Pydantic models mirroring the legacy API's wire format
  infrastructure/
    customer_http_client.py  # HTTP client for the legacy REST API
  application/
    customer_service.py  # Business rules (find-by-any-field, delegates CRUD)
  mcp/
    server.py             # Wires tools/resource/prompt onto a FastMCP instance
    tools/                 # One module per tool (SRP)
    resources/
    prompts/
  __main__.py              # Entry point — connects the server to stdio transport
tests/
  conftest.py               # Shared MCP client helper (async context manager)
  test_customer_service.py  # Unit tests (fake HTTP client, no network)
  test_customer_tools.py    # Integration tests via a real MCP stdio client
  test_api_info_resource.py
  test_find_customer_prompt.py
```

`CustomerService` receives its `CustomerHttpClient` via constructor injection (composed in `mcp/server.py`), so it can be tested in isolation with a fake client — no legacy API or network needed for `test_customer_service.py`.

---

## Prerequisites

- **Python 3.12+**
- [**uv**](https://docs.astral.sh/uv/) (recommended) or `pip`
- The legacy `nodejs-fastify-mongodb-crud` API running at `http://localhost:9999` (only needed to actually call the tools or run the integration tests — see that project's `docker-compose.yml`: `npm run docker:infra:up`)

---

## Installation

```bash
uv sync
```

---

## Using in VS Code

### 1. Add the MCP server configuration

Create (or open) `.vscode/mcp.json` in your workspace:

```json
{
  "servers": {
    "customers-mcp": {
      "command": "uv",
      "args": ["run", "python", "-m", "customers_mcp"]
    }
  }
}
```

### 2. Reload VS Code

Command Palette (`Cmd+Shift+P`) → **Developer: Reload Window**.

### 3. Use it in Copilot Chat

```
List all customers
```

```
Create a customer named "Ana" with phone "999-000-111"
```

```
Find the customer named John
```

---

## Running tests

```bash
uv run pytest
```

`test_customer_service.py` runs standalone (no dependencies). The other test files spawn the real MCP server and call the legacy API, so they require it running at `http://localhost:9999` first.

---

## Available commands

| Command | Description |
|---|---|
| `uv run python -m customers_mcp` | Start the server (used by MCP clients) |
| `uv run pytest` | Run all tests |
| `uv run ruff check .` | Lint |
| `uv run ruff format .` | Format |