# Mern-Chat-App MCP Server

This is a standalone [Model Context Protocol](https://modelcontextprotocol.io) server
generated for the `Mern-Chat-App` repository. It exposes two kinds of tools:

**Code-reading tools** (bundled repo source + Claude's architecture notes):

- `list_files(pattern?)` — list bundled files, optionally filtered by glob (e.g. `*.py`)
- `read_file(path)` — read a file's contents
- `search_code(query, regex?, max_results?)` — search across the bundled source
- `get_repo_overview()` — the Claude-generated architecture overview
- `get_file_summary(path)` — the Claude-generated summary for one file

**API-calling tools** (auto-generated, see `server.py` for the actual list — search for
`@mcp.tool()`) — one per endpoint Claude found this app's own frontend actually
calling. These call the **real, already-deployed instance** of this app's backend —
they don't run any code from this repo themselves. **They do nothing until you set
`API_BASE_URL`** (see below) to point at where you've deployed the actual application.

This server has **no dependency on Claude, Anthropic, or any external API at runtime**
— it only needs the `mcp` package (which pulls in `httpx` for the API-calling tools),
and works with any MCP-compatible client (Claude Desktop, Claude Code, or any other
agent that can launch a stdio MCP server).

## Run it

```bash
pip install -r requirements.txt   # or: pip install "mcp[cli]"
python server.py
```

## Use it from Claude Desktop / Claude Code

Add to your MCP client config (e.g. `claude_desktop_config.json`):

```json
{
  "mcpServers": {
    "mern-chat-app": {
      "command": "python",
      "args": ["/absolute/path/to/mern-chat-app-mcp-server/server.py"]
    }
  }
}
```

Or with the Claude Code CLI:

```bash
claude mcp add mern-chat-app -- python /absolute/path/to/mern-chat-app-mcp-server/server.py
```

Any other MCP-compatible agent that can launch a stdio child process can use this the
same way.

## Try it standalone

```bash
mcp dev server.py
```

This opens the MCP Inspector so you can call the tools manually before wiring it into
an agent.

## Connecting the API-calling tools to your real app

The generated API-calling tools are proxies — they need to know where your actual
app is running and (if it requires login) how to authenticate. Two environment
variables:

| Variable | Meaning |
|---|---|
| `API_BASE_URL` | Base URL of your **already-deployed, live** instance of this app's backend (e.g. `https://my-app.onrender.com`). Without this, every API-calling tool returns a clear error instead of doing nothing silently. |
| `AUTH_MODE` | `service` (default) or `passthrough` — see below. |

**`AUTH_MODE=service`** (default) — one shared credential for every call:

```
AUTH_MODE=service
TARGET_API_TOKEN=<a token your app accepts, e.g. from its own login endpoint>
```

Every tool call sends `Authorization: Bearer <TARGET_API_TOKEN>` to your app. Simple,
but every call acts as this one identity — right for single-operator/admin use, not
for an app with many separate end users. If the token expires, update the
`TARGET_API_TOKEN` env var (a fast restart, not a rebuild, on hosts like Render) — no
redeploy needed.

**`AUTH_MODE=passthrough`** — for apps with many end users, each with their own login:

```
AUTH_MODE=passthrough
```

No credential is stored here at all. Whatever `Authorization` header arrives on
*this server's own* incoming request is forwarded as-is to your app's API — each
caller acts as themselves. **This means whatever calls this MCP server on a given
user's behalf must already hold that user's own valid token for your app and pass it
through** — the same way your own app's frontend already does today. This server
never stores, inspects, or manages those tokens; it's a pure relay.

## Deploy remotely (e.g. Render)

⚠️ **This bundles your entire repository's source code, and (once configured above)
can call your real app's API.** Deployed with no auth, `read_file`/`search_code`
would let anyone with the URL read your whole repo (including any secrets
accidentally committed to it), and the API-calling tools would be usable by anyone
with the URL too. Don't deploy without the token check below.

By default this server runs over **stdio** (a local subprocess, no network exposure).
To run it as a remote HTTP server instead, set:

| Variable | Value |
|---|---|
| `MCP_TRANSPORT` | `streamable-http` |
| `MCP_AUTH_TOKEN` | a strong random secret — required when `AUTH_MODE=service`; every request must send it back (see below for `AUTH_MODE=passthrough`, which skips this in favor of requiring *some* per-caller Authorization header instead) |

**On Render:** this project includes a `render.yaml` blueprint. In the Render
dashboard, choose **New → Blueprint**, point it at a git repo containing these files,
and Render will create the service, install `requirements.txt`, run `python
server.py`, and auto-generate `MCP_AUTH_TOKEN` for you (visible in the service's
Environment tab afterward). Render assigns the port automatically — the server reads
it from the `PORT` env var Render sets (defaults to `10000` if unset, matching
Render's own convention).

**Calling the deployed server:** MCP clients that support remote servers connect to
`https://<your-service>.onrender.com/mcp` and must include the header:

```
Authorization: Bearer <the MCP_AUTH_TOKEN value>
```

Requests missing or mismatching that header get HTTP 401 — the repository source is
never served without it.