# finpay-mcp-server

An MCP (Model Context Protocol) server that exposes a **fictional payment domain** as tools, resources, and prompt templates. Connect Claude Desktop (or any MCP client) and reason over the FinPay platform — transactions, payment hubs, microservices, and system health.

Built with TypeScript + Node.js using the official `@modelcontextprotocol/sdk`.

---

## What it demonstrates

- Full MCP server implementation: **8 tools**, **2 resources**, **2 prompts**
- Production-quality TypeScript with strict type checking throughout
- Tool schema design using zod — every parameter is typed and described
- MCP governance: tool naming conventions, schema versioning, access control patterns
- stdio transport for Claude Desktop; optional HTTP transport for remote clients

---

## Quickstart

**Prerequisites:** Node.js 22+, npm

```bash
git clone https://github.com/your-handle/finpay-mcp-server
cd finpay-mcp-server
npm install
npm run build
```

**Connect to Claude Desktop:**

Add to `~/Library/Application Support/Claude/claude_desktop_config.json`:

```json
{
  "mcpServers": {
    "finpay": {
      "command": "node",
      "args": ["/Users/ThanhNguyen/AI_WS/finpay-mcp-server/dist/index.js"]
    }
  }
}
```

Restart Claude Desktop. The FinPay tools will appear in the tool panel.

**Run in development mode (hot reload):**

```bash
npm run dev
```

**Run with HTTP transport (Streamable HTTP, stateless):**

```bash
node dist/index.js --transport http --port 3100
```

To require an API key on the HTTP transport:

```bash
MCP_API_KEY=your-secret node dist/index.js --transport http --port 3100
```

Clients must then send `Authorization: Bearer your-secret` with every request.

---

## Tools

All tools operate on in-memory fixture data — no API keys or external services required (except `search_docs`).

### Transactions

| Tool | Description |
|---|---|
| `get_transaction` | Look up a transaction by ID (`TXN-XXXXXXXXX`) |
| `list_transactions` | List recent transactions. Filterable by `status`, `hubId`, and `limit` (max 50) |

### Payment Hubs

| Tool | Description |
|---|---|
| `get_payment_hub` | Get a hub's details: status, currencies, latency, 24h success rate |
| `list_payment_hubs` | List all hubs (GlobalPay, SwiftRoute, MobileFirst, RegionalX) |

### Services

| Tool | Description |
|---|---|
| `explain_service` | Describe a microservice: purpose, dependencies, dependents, health |
| `list_services` | List all microservices in the FinPay platform |

### System

| Tool | Description |
|---|---|
| `get_system_health` | Unified health snapshot: overall status, per-service health, per-hub metrics, active alerts |
| `search_docs` | Full-text search via docu-rag API (requires `DOCU_RAG_URL` env var) |

---

## Resources

Resources expose read-only data that the LLM can load directly into context.

| URI | Content |
|---|---|
| `finpay://services/catalog` | JSON catalog of all services with full metadata |
| `finpay://architecture/overview` | Markdown system architecture overview |

---

## Prompts

Prompt templates inject structured system context to guide LLM behaviour.

### `architecture-review`
Loads the full service catalog, hub list, and dependency graph. Asks the model to conduct a structured architecture review.

**Optional argument:** `focus` — area to concentrate on (e.g., `resilience`, `scalability`, `security`)

### `incident-triage`
Loads current system health, recent FAILED/DEGRADED transactions, and hub health metrics. Guides the model through a structured incident triage.

**Optional argument:** `transactionId` — specific transaction to investigate

---

## Configuration

| Variable | Default | Description |
|---|---|---|
| `DOCU_RAG_URL` | — | Base URL of the docu-rag API. Enables `search_docs` tool. |
| `LOG_LEVEL` | `info` | `debug` \| `info` \| `warn` \| `error` |
| `LOG_FILE` | `logs/app.log` | Path to the log file. Directory is created automatically on startup. |
| `MCP_API_KEY` | — | HTTP transport only. If set, all requests must include `Authorization: Bearer <value>`. |

No API keys required for the core 7 tools. The server runs fully without any `.env` file.

Copy `.env.example` if you want to enable the optional `search_docs` tool:

```bash
cp .env.example .env
# Set DOCU_RAG_URL=http://localhost:8001
```

---

## Example Interactions

Once connected to Claude Desktop, try:

```
Show me all FAILED transactions in the last hour.
```

```
Which payment hub has the lowest success rate right now?
```

```
Explain the dependency chain for hub-adapter-service and tell me what breaks if compliance-service goes down.
```

```
Run an architecture review focused on resilience.
```

```
Triage the incident for transaction TXN-100000011.
```

---

## Governance

### Tool Naming Conventions

- Names are `snake_case`, verb-first for actions: `get_`, `list_`, `search_`, `explain_`
- Tool names are a **public API** — never renamed once published
- Breaking changes (removed/renamed params) require a new tool name (e.g., `get_transaction_v2`) and a deprecation notice before the old one is removed

### Schema Versioning

This server follows semantic versioning (`package.json`):

| Change type | Version bump |
|---|---|
| New optional parameter or new response field | Patch (0.0.X) |
| New tool, new resource, new prompt | Minor (0.X.0) |
| Removed tool, removed required param, renamed tool | Major (X.0.0) only after deprecation period |

### Access Control

**stdio transport** inherits OS user permissions. It is suitable for local, trusted use only (Claude Desktop on your own machine).

**HTTP transport** is intended for hosted deployments. In production, all tool calls should require `Authorization: Bearer <token>`. The current HTTP transport implementation accepts a `--api-key` flag to enable simple token validation. Scope-based access control (restricting which tools a given API key can call) is documented in `docs/decisions/ADR-001-transport-strategy.md` and recommended for any multi-tenant deployment.

All tools in this server are **read-only** over mock data. In a production server with write access to real systems, each mutating tool would require an explicit capability scope.

---

## Development

```bash
npm run typecheck   # type-check without building
npm test            # run tests (vitest)
npm run lint        # eslint
npm run build       # compile to dist/
```

CI runs on every push: type-check → lint → test.

---

## Project Structure

```
src/
├── index.ts                  # Entry point — CLI arg parsing, transport selection
├── server.ts                 # McpServer setup, registers all tools/resources/prompts
├── logger.ts                 # File + stderr logger (writes to logs/app.log)
├── logging-transport.ts      # Transport wrapper — access log per request/response cycle
├── tools/
│   ├── transactions.ts       # get_transaction, list_transactions
│   ├── hubs.ts               # get_payment_hub, list_payment_hubs
│   ├── services.ts           # explain_service, list_services
│   ├── health.ts             # get_system_health
│   └── docs.ts               # search_docs (docu-rag proxy, requires DOCU_RAG_URL)
├── resources/
│   ├── services-catalog.ts   # finpay://services/catalog
│   └── architecture-overview.ts  # finpay://architecture/overview
├── prompts/
│   ├── architecture-review.ts
│   └── incident-triage.ts
└── data/
    ├── transactions.json     # 20 fixture transactions
    ├── hubs.json             # 4 fixture hubs
    └── services.json         # 7 fixture services
logs/                         # Runtime log output (gitignored)
└── app.log
docs/decisions/               # Architecture Decision Records
tests/
└── tools/                    # Unit tests for all tool modules
```

---

## License

MIT