# Sol MCP App

Sol MCP is a read-only ChatGPT App facade over the existing Sol APIs.

## Public endpoint

- App URL: `https://sol.system42.one/api/mcp/sol`
- Health URL: `https://sol.system42.one/api/mcp/sol/health`
- Legacy SSE URL: `https://sol.system42.one/api/mcp/sol/sse`

## ChatGPT App creation settings

These are the settings that matched the live connector behavior during ChatGPT-side registration:

- Name: `Sol`
- Description: `Read-only grounded chat, search, fetch, and live status`
- MCP Server URL: `https://sol.system42.one/api/mcp/sol`
- Authentication: `No Auth`

Important notes from live registration attempts:

- `Mixed` and `OAuth` are wrong for this connector. ChatGPT explicitly reported that the Sol MCP endpoint does not implement OAuth.
- `https://sol.system42.one/api/mcp/sol/sse` is not the right connector URL for ChatGPT app creation. The creation flow timed out against the SSE endpoint because it is a legacy long-lived transport rather than the primary MCP entrypoint.
- The root MCP URL is the intended connector URL for ChatGPT app registration.
- After creation, the connector may not appear immediately in the public browse grid. The authoritative verification is whether `@Sol` resolves in chat and successfully calls tools.

## Local service

- Local port: `127.0.0.1:8898`
- Source: `/home/david/random/apps/sol-mcp/server.mjs`
- Unit: `/home/david/.config/systemd/user/sol-mcp.service`

## Exposed tools

- `search`
  Search the Sol knowledge index and return compact document handles.
- `fetch`
  Read a full Sol document by id returned from `search`.
- `queryKnowledge`
  Return scored semantic-search hits from the Sol knowledge API.
- `queryChat`
  Run a grounded text chat turn against the Sol chat API.
- `getSystemStatus`
  Return current Sol runtime health, telemetry, and service state.

## Operational notes

- The MCP layer is intentionally read-only.
- Sol GPT Actions and ChatGPT Apps are separate attachment models. Keep the GPT as the personality/orchestration surface and the MCP app as the capability surface.
- The MCP server proxies to the existing Sol services:
  - chat: `127.0.0.1:8895`
  - knowledge: `127.0.0.1:8892`
  - dashboard: `127.0.0.1:8896`
- Live connector verification succeeded when ChatGPT resolved `@Sol` and invoked the `Query Chat` tool from a normal conversation.
- `queryChat` normalizes ChatGPT-style wrapped prompts such as `The user says: '@Sol hello'. Respond with a brief greeting.` down to the underlying user intent before forwarding them.
- `queryChat` always fetches live status before answering; greeting and server-status turns defer to the Sol chat API's native live-site-state path, while other turns get the live traffic/sensor/runtime block merged into page context.
- Sensor readouts are part of the shared live context, not a separate optional tool-only detail.

## Deploy / reload

```bash
systemctl --user daemon-reload
systemctl --user enable --now sol-mcp.service
systemctl --user restart sol-mcp.service
systemctl --user reload caddy-sol37.service
```

## Smoke test

```bash
curl -s https://sol.system42.one/api/mcp/sol/health | python3 -m json.tool
```

SDK-level smoke test:

```bash
node --input-type=module <<'EOF'
import { Client } from '@modelcontextprotocol/sdk/client/index.js';
import { StreamableHTTPClientTransport } from '@modelcontextprotocol/sdk/client/streamableHttp.js';

const transport = new StreamableHTTPClientTransport(new URL('https://sol.system42.one/api/mcp/sol'));
const client = new Client({ name: 'sol-mcp-smoke', version: '0.1.0' }, { capabilities: {} });
await client.connect(transport);
console.log((await client.listTools()).tools.map(tool => tool.name));
await transport.close();
EOF
```