# observe-mcp

[![M8ven Verified](https://m8ven.ai/badge/mcp/avaneshj-observe-mcp-sfe3ww?variant=verified&v=fa8f6f289f7a33d92f7ad021672c17fc)](https://m8ven.ai/mcp/avaneshj-observe-mcp-sfe3ww?s=readme)
[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](LICENSE)

> Give your AI agent grounded, read-only access to production: Postgres, Sentry, GitHub. Built for Cursor, Claude Desktop, Claude Code, Zed, and any other MCP client.

Stop asking agents "why might the API be slow?" and hearing a guess. Let them look.

```
You: Why did signups drop yesterday?

Agent (via observe-mcp):
- Queried pg_describe_schema → found `users` table
- Ran: SELECT date_trunc('day', created_at) AS d, count(*) FROM users
         WHERE created_at > now() - interval '14 days' GROUP BY 1
- Correlated: sentry_list_issues returned a spike in `AuthProvider.initialize`
              errors on 2026-11-05 at 14:32
- Cross-ref:  gh_recent_commits shows commit abc123 "auth: add new SSO flow"
              merged at 14:28 the same day

Yesterday's signup drop lines up with commit abc123. Revert that and
re-check.
```

## Why this exists

General coding agents can reason about code, but they can't reliably answer **questions grounded in your live production state**. They don't have your database, your error feed, or your deploy history. `observe-mcp` plugs that gap — safely.

## Install

### From source (works today)
```bash
git clone https://github.com/AvaneshJ/observe-mcp.git
cd observe-mcp
npm install
npm run build
node dist/index.js wizard   # interactive setup
node dist/index.js tui      # terminal dashboard
node dist/index.js inspect  # web inspector on http://localhost:3030
```

### From npm (once published)
```bash
npx bharatcode-observe-mcp wizard
```

The wizard creates `~/.config/observe-mcp/config.yaml` with `chmod 600`.

### Wire it into an agent

**Claude Desktop** — add to `claude_desktop_config.json`:
```json
{
  "mcpServers": {
    "observe": {
      "command": "node",
      "args": ["/absolute/path/to/observe-mcp/dist/index.js"]
    }
  }
}
```
Swap `command`/`args` for `npx -y bharatcode-observe-mcp` once the package is on npm.

**Cursor** — the same block in `~/.cursor/mcp.json`.

## Try it in 60 seconds (no real prod needed)

```bash
git clone https://github.com/AvaneshJ/observe-mcp.git
cd observe-mcp
npm install && npm run build
docker compose -f demo/docker-compose.yaml up -d
OBSERVE_MCP_CONFIG=./demo/config.demo.yaml BHARATCODE_API_KEY=dummy node dist/index.js
```

Then in Claude Desktop, ask: *"How many orders failed in the last 24 hours and which products were involved?"*

## Tools exposed to the agent

| Tool | What it does |
|---|---|
| `pg_describe_schema` | Lists tables + columns the agent may query (deny-listed columns are hidden). |
| `pg_query` | Runs a read-only `SELECT`. Only `SELECT` allowed. `LIMIT` is injected. Timeout enforced. |
| `sentry_list_issues` | Lists recent Sentry issues for an allow-listed project. |
| `sentry_get_event` | Fetches one event payload. |
| `gh_recent_commits` | Lists recent commits on an allow-listed repo. |
| `gh_recent_releases` | Lists recent releases (deploys). |
| `correlate_events` | Merges Sentry errors, GitHub commits and releases into one sorted timeline for a time window — the single most useful tool for "what broke right around X?". |

## Safety

This is the part you should read before pointing it at real data. See **[SECURITY.md](SECURITY.md)**.

Short version:
- **Postgres**: refuses superusers. Only `SELECT`. Column-level redaction. Auto-`LIMIT`. Query timeout.
- **Prompt injection**: every result wrapped in `<untrusted-data>` tags with an explicit note telling the agent not to follow instructions inside.
- **Credentials**: live only in a `chmod 600` config, never in results, never in audit logs.
- **Audit**: every call appended to `~/.config/observe-mcp/audit.log`.
- **Budget**: hard daily cap on calls (default 1000).
- **Network**: only the hosts you configure plus the BharatCode base URL.

## How BharatCode is used

The MCP uses BharatCode's model API for internal safety passes before any data leaves the server:

1. **Regex PII redaction** (always on) — strips emails, Indian phone numbers, PAN, Aadhaar, card numbers, IPs from every result.
2. **LLM PII redaction** — when a BharatCode key is configured, a model pass catches odd formats regex misses (names paired with addresses, passport numbers, bank accounts).
3. **Future (day 3):** suspicious-query shape analysis and large-result summarization.

If no BharatCode key is set the server still works in regex-only mode — set `safety.redact_pii: false` to disable even that.

## License

MIT. See [LICENSE](LICENSE).

---

Built for the BharatCode Build League.