# MCP Tool Server + Live Agent Observability Dashboard

A small, production-shaped MVP for demonstrating MCP tool use with real persistence and live tracing.

## What is here

- **MCP server** — Node/TypeScript using the official `@modelcontextprotocol/server` SDK.
- **4 tools** — `createTask`, `queryTasks`, `updateTask`, `checkServerHealth`.
- **MongoDB** — task and trace collections with indexes.
- **Observability API** — Express API that reads trace history and accepts trace events from the MCP process.
- **Socket.io** — every completed tool call is pushed to connected dashboards immediately.
- **React dashboard** — deliberately plain: trace list, filters, timing/status badges, and JSON detail panels.
- **Tests** — Vitest tests for task behavior, tracing, HTTP endpoints, and the React shell.
- **Claude wiring** — example configuration for Claude Desktop and Claude Code.

## Runtime shape

```text
Claude Desktop / Claude Code
          |
          | MCP over stdio
          v
  +-------------------+
  |   MCP server      |
  | 4 real tool calls |
  +---------+---------+
            |
       MongoDB task + trace writes
            |
            +----------------------+
            |                      |
            v                      v
  +-------------------+    +-------------------+
  | Observability API | -> | Socket.io clients |
  +-------------------+    +-------------------+
            ^
            |
      React dashboard
```

The dashboard does **not** sit in the MCP protocol path. If the dashboard is down, the MCP process can still save the trace to MongoDB. When the dashboard comes back, it reads the persisted trace history. The HTTP notification exists only to make the UI feel live.

## Prerequisites

Node.js 20+ is required for the current MCP TypeScript SDK. MongoDB can be local, Atlas, or the included Docker service.

```bash
cp .env.example .env
npm install
docker compose up -d mongo
```

The current MCP TypeScript SDK v2 is the stable line and uses `McpServer` with `registerTool`; stdio is the local host transport. See the official SDK docs for the current API. 

### Run the apps

Terminal 1 — observability API:

```bash
npm run dev -w @mcp-observability/observability
```

Terminal 2 — React dashboard:

```bash
npm run dev -w @mcp-observability/dashboard
```

The dashboard will be at `http://localhost:5173` and the observability API at `http://localhost:4000`.

Terminal 3 — optional standalone MCP process for Inspector:

```bash
npm run inspect:mcp
```

## Claude Desktop

Build the MCP server once:

```bash
npm run build -w @mcp-observability/core
npm run build -w @mcp-observability/mcp-server
```

Copy the example in `config/claude_desktop.example.json` into your Claude Desktop MCP config and replace the absolute path with the path to this repository. Keep `OBSERVABILITY_URL` pointing at the running observability API.

The MCP process writes protocol traffic to stdout and diagnostics to stderr. Do not add ordinary `console.log` calls to the MCP process.

## Claude Code

Use `config/claude_code.example.json` as the shape for a project-level `.mcp.json`. The command can point to the built `dist/index.js` or use `npx tsx` during development.

## Live demo

1. Start MongoDB.
2. Start the observability API.
3. Start the React dashboard.
4. Launch Claude Desktop or Claude Code with this MCP server configured.
5. Ask: `Create a high priority task called fix login bug.`
6. Ask: `List the open tasks.`
7. Ask: `Mark the fix login bug task as in_progress.`
8. Ask: `Is the task server healthy?`
9. Keep the dashboard visible. Each tool call appears as a trace, including arguments, status, duration, and result.

## Tool contract

### createTask

Creates a task in `tasks`.

```json
{
  "title": "fix login bug",
  "priority": "high"
}
```

### queryTasks

Lists tasks with optional text, status, and priority filters.

```json
{
  "text": "login",
  "status": "open",
  "limit": 25
}
```

### updateTask

Changes a task's title, priority, or status.

```json
{
  "taskId": "...",
  "status": "in_progress"
}
```

### checkServerHealth

Pings MongoDB and returns service health plus latency.

## Testing

```bash
npm test
npm run typecheck
npm run build
```

The tests deliberately keep the database boundary injectable so most behavior can run without a real MongoDB instance. For a real integration environment, point `MONGODB_URI` at a dedicated test database and add a Mongo-backed test stage in CI.

## Tradeoffs / next production steps

This is an MVP, not a hosted multi-tenant tracing product. The important boundary is already there: MCP tool execution is instrumented, traces are durable, and the UI consumes a simple event stream. A production system would add authentication, redaction policy, trace correlation across model turns, retention jobs, sampling, rate limiting, pagination cursors, and multi-instance event delivery.