# Mindset AI — Sample MCP Server & Onboarding

A small, runnable example of an **MCP (Model Context Protocol) server that connects to a Mindset AI agent**. It calls only free public APIs (no keys, no customer data), so you can run it end-to-end immediately and use it as a reference for building your own.

> **New here? Read [`START_HERE.md`](START_HERE.md) first.** It gives the global view of how a Mindset MCP server, agent, and widget fit together, then points you at the right files in order. It's written so a customer's AI coding agent can orient itself end-to-end.
>
> **In one sentence:** this repo has **3 small tool servers** (weather, profile, wikipedia) and **one translator — [`mcp-http-server.js`](mcp-http-server.js) (`npm run start:mcp`)** — that re-serves all **5** of their tools at a single `/mcp` endpoint in the language Mindset speaks (JSON-RPC + bearer auth + `x-user-id` headers). You give AMS that one URL; the stdio (`start:weather`) and legacy REST (`start:http`) runners are **not** Mindset-compatible.

---

## The 3 sample servers (5 tools)

| Server | Tools | Public API | Teaches |
|--------|-------|------------|---------|
| **weather** | `get_weather` | Open-Meteo | the simplest possible tool (one param) + the **widget** example |
| **profile** | `get_my_profile` | none (synthetic) | **identity & security** — reads `x-user-id`, takes no `user_id` parameter |
| **wikipedia** | `search_wikipedia`, `get_wikipedia_article`, `get_wikipedia_summary` | MediaWiki | a multi-tool **search → detail** flow |

All three are exposed together, in a Mindset-compatible way, by the translator (`npm run start:mcp`). See [`START_HERE.md`](START_HERE.md) → "How this repo is wired".

## Onboarding docs (in [`docs/`](docs/))

| Doc | Covers |
|---|---|
| [`SETUP.md`](docs/SETUP.md) | Run the server locally + smoke test |
| [`SECURITY.md`](docs/SECURITY.md) | **How the agent and server authenticate** — bearer vs `x-user-id`, the identity headers, the never-trust-a-param rule |
| [`DEPLOYMENT.md`](docs/DEPLOYMENT.md) | Ship to Cloud Run (public HTTPS URL for AMS) |
| [`AMS_CONFIGURATION_GUIDE.md`](docs/AMS_CONFIGURATION_GUIDE.md) | Register the server, create the agent, attach the widget |
| [`WIDGETS.md`](docs/WIDGETS.md) | The `show_*` widget mechanism (worked example: [`widgets/WeatherWidget.mdx`](widgets/WeatherWidget.mdx)) |
| [`MINDSET_API.md`](docs/MINDSET_API.md) | Embed the agent in a page (SDK v3) + provision sessions (REST) |

The transport contract the Mindset agent speaks is in [`MINDSET_AI_COMPLIANCE.md`](MINDSET_AI_COMPLIANCE.md). Canonical platform reference: **https://docs.mindset.ai**.

---

## Quick start

```bash
npm install

# Start the Mindset-compatible server (the translator). Prints an API key on first run.
export MCP_API_KEY="$(node -e "console.log(require('crypto').randomBytes(32).toString('hex'))")"
npm run start:mcp        # → http://localhost:8080/mcp
```

Smoke-test it:

```bash
# List tools (no user headers needed)
curl -s -X POST http://localhost:8080/mcp \
  -H "Authorization: Bearer $MCP_API_KEY" -H "Content-Type: application/json" \
  -d '{"jsonrpc":"2.0","id":1,"method":"tools/list","params":{}}'

# Call a tool (tool execution requires the identity headers)
curl -s -X POST http://localhost:8080/mcp \
  -H "Authorization: Bearer $MCP_API_KEY" -H "Content-Type: application/json" \
  -H "x-user-id: test-user" -H "x-app-uid: test-app" \
  -d '{"jsonrpc":"2.0","id":2,"method":"tools/call","params":{"name":"get_weather","arguments":{"location":"London"}}}'
```

Full walkthrough: [`docs/SETUP.md`](docs/SETUP.md).

## Testing

```bash
node test-mcp-compliance.js "$MCP_API_KEY"   # 10-point Mindset compliance suite
npx @modelcontextprotocol/inspector http://localhost:8080/mcp   # interactive MCP Inspector
```

There is also an interactive browser tester at [`public/test.html`](public/test.html).

## Other entry points (NOT Mindset-compatible)

These exist for local experimentation only — do **not** register them in AMS:

- `npm run start:weather` / `start:wikipedia` — single server over **stdio** (for Claude Desktop / MCP Inspector)
- `npm run start:http` — legacy plain-REST API
- `npm run start:multi-mcp` — the alternate TypeScript build under `src/` (per-server `/mcp/<name>` endpoints)

For Mindset, always use **`npm run start:mcp`**.

## License

See [`LICENSE`](LICENSE).