# MCP Platform

A reusable **Model Context Protocol (MCP) Platform** for hosting MCP servers, tool registries, and skills-powered AI workflows over HTTP.

## What This Repo Is

This is the **platform repo** — shared runtime infrastructure that any project-specific MCP service builds on top of.

| Repo type | Purpose | Example |
|---|---|---|
| **Platform** (this repo) | HTTP server, tool registry, validation, auth, logging | `MCP` |
| **Skills content** | Reusable AI agent skill definitions (SKILL.md + references) | `AI_AGENT_SKILLS` |
| **Project service** | Business-logic tools for a specific product | `ghostfolio-mcp-server` |

A project service imports this platform, registers its own tools, and pins a version of the skills content repo for context retrieval.

## Architecture

```
AI_AGENT_SKILLS (content)
        ↓ mounted / submodule
  Project MCP Service (e.g. ghostfolio-mcp-server)
        ↓ depends on
    MCP Platform (this repo) ← HTTP transport, registry, validation
        ↓ serves
    Claude / AI client via JSON-RPC over HTTP
```

## Quickstart

```bash
# 1. Install dependencies
npm install

# 2. Set environment variables (optional)
export PORT=3100
export MCP_API_KEY=your-secret-key   # omit to disable auth

# 3. Run the dev server
npm run dev

# 4. Health check
curl http://localhost:3100/health
# → { "status": "ok", "timestamp": "..." }

# 5. List registered tools
curl http://localhost:3100/tools
# → { "tools": [ { "name": "echo", ... } ] }

# 6. Call a tool via JSON-RPC
curl -X POST http://localhost:3100/rpc \
  -H "Content-Type: application/json" \
  -H "x-mcp-api-key: your-secret-key" \
  -d '{"method":"echo","params":{"message":"hello"},"id":1}'
# → { "jsonrpc": "2.0", "result": { "echo": "hello", ... }, "id": 1 }
```

## Adding a Tool

1. Create a handler function: `(params, context) => result`
2. Define a JSON schema for the input parameters.
3. Register it in `src/server/toolRegistry.ts` or via `registerTool()`.
4. See [docs/adding_a_tool.md](docs/adding_a_tool.md) for the full guide.

## Deployment

Designed for **Railway** with HTTP transport (no stdio).

- Set `PORT` via Railway env vars (Railway auto-assigns).
- Set `MCP_API_KEY` for production auth.
- See [docs/deployment_railway.md](docs/deployment_railway.md) for step-by-step instructions.

## Project Structure

```
src/
  index.ts              # Entrypoint — bootstraps server
  server/               # HTTP server, transport, tool registry
  skills/               # Skills file loader and resolver
  validation/           # JSON schema + SQL safety gate
  auth/                 # API key auth + request context
  logging/              # Structured logger + trace
  utils/                # Error classes, env helpers
docs/                   # Architecture, deployment, guides
templates/              # Tool, skill, and service repo templates
examples/               # Minimal working tool example
```

## License

MIT