# LKPlanWise MCP Server

Stateless MCP adapter for the LKPlanWise Go REST API. AI clients call curated
MCP tools over Streamable HTTP; this service validates tool contracts and
forwards each caller's Bearer credential to the Go backend. It does not connect
to PostgreSQL or duplicate financial business rules.

## Architecture

```text
AI Agent
  -> MCP Streamable HTTP
  -> Python FastMCP server
  -> HTTPX + request-scoped Bearer credential
  -> LKPlanWise Go API
  -> service layer
  -> PostgreSQL
```

## Requirements

- Python 3.12+
- [uv](https://docs.astral.sh/uv/)
- Running LKPlanWise Go backend

## Setup

```powershell
uv python install 3.12
uv sync
Copy-Item .env.example .env
```

Configure `LKPLANWISE_MCP_BACKEND_BASE_URL` in `.env`, then run:

```powershell
uv run lkplanwise-mcp-server
```

The MCP endpoint is available at:

```text
http://127.0.0.1:8000/mcp
```

The operational health endpoint is:

```text
http://127.0.0.1:8000/healthz
```

## First tool

`list_financial_accounts` lists accounts owned by the authenticated user. The
MCP request must include:

```http
Authorization: Bearer <credential>
```

The credential is forwarded to `GET /financial-accounts` on the Go backend.
The Go backend remains responsible for validating the credential, resolving
the user, enforcing ownership, and applying business rules.

The current Go middleware accepts JWT access tokens. Before using `sk-lk-*`
Agent API keys end to end, add a restricted Agent-authenticated route group to
the Go backend or extend only the intended resource routes with Agent API key
authentication.

## Development

```powershell
uv run pytest
uv run ruff check .
uv run ruff format --check .
uv run mypy
```

Test the running server with MCP Inspector:

```powershell
npx -y @modelcontextprotocol/inspector
```

Connect the Inspector to `http://127.0.0.1:8000/mcp` and provide the
`Authorization` header in its connection settings.

## Design rules

- Tools are curated user actions, not an automatic mirror of REST endpoints.
- The MCP service never connects directly to the database.
- Credentials are request-scoped and must never be logged or returned.
- Reads and writes are separate tools with accurate safety annotations.
- Consequential write tools require idempotency support in the Go backend.