intentos-mcp 1.0.0

package/README.md

@@ -0,0 +1,121 @@
+# intentos-mcp
+
+> MCP server for IntentOS — gives any MCP-compatible AI client read/write access to a user's personal preference ledger.
+
+## What it does
+
+[IntentOS](https://github.com/L0nE-F0x/intentos) is a personal preference ledger — a sovereign source of truth for what someone likes, who they trust, and what's worked or failed for them. This MCP server exposes that ledger to any agent harness that speaks the [Model Context Protocol](https://modelcontextprotocol.io): Claude Desktop, Cursor, Cline, Continue, OpenWebUI, and most modern agentic clients.
+
+When connected, your agent can:
+
+- **`query_preferences`** — semantic search across the ledger ("what kind of coffee does the user love?")
+- **`get_category`** — read everything in a category ("show me their full headphones config")
+- **`check_vendor_trust`** — check if a brand is trusted/distrusted before recommending it
+- **`add_preferences`** — append new preferences or record purchase outcomes (write scope)
+- **`record_audit_event`** — agents self-report what they did with the data
+
+## Quick start
+
+### 1. Issue an API key in IntentOS
+
+Go to your IntentOS dashboard → **Agents → Connect agent** → name it ("Claude Desktop", "Cursor", whatever) → pick scopes → **Issue API key**. Copy the `sk_intent_…` key. (Shown once — store it safely.)
+
+Recommended scopes for read-only agents:
+- `preferences:read`
+- `trust:read`
+- `query:semantic`
+
+Add `preferences:write` and `purchases:write` if you want the agent to record outcomes.
+
+### 2. Build the server
+
+From the IntentOS repo:
+
+```bash
+cd mcp
+npm install
+npm run build
+```
+
+This compiles to `mcp/dist/index.js`. Note the absolute path — you'll need it.
+
+### 3. Configure your MCP client
+
+#### Claude Desktop
+
+Edit `claude_desktop_config.json`:
+
+- **macOS**: `~/Library/Application Support/Claude/claude_desktop_config.json`
+- **Windows**: `%APPDATA%\Claude\claude_desktop_config.json`
+- **Linux**: `~/.config/Claude/claude_desktop_config.json`
+
+```json
+{
+  "mcpServers": {
+    "intentos": {
+      "command": "node",
+      "args": ["/absolute/path/to/intentos/mcp/dist/index.js"],
+      "env": {
+        "INTENTOS_API_KEY": "sk_intent_...",
+        "INTENTOS_BASE_URL": "https://useintentos.com"
+      }
+    }
+  }
+}
+```
+
+Restart Claude Desktop. You should see the **🔌 intentos** indicator in the bottom-right of any chat. Try: *"What kind of headphones do I love?"*
+
+#### Cursor
+
+Open Cursor settings → **MCP Servers** → add:
+
+```json
+{
+  "intentos": {
+    "command": "node",
+    "args": ["/absolute/path/to/intentos/mcp/dist/index.js"],
+    "env": {
+      "INTENTOS_API_KEY": "sk_intent_...",
+      "INTENTOS_BASE_URL": "https://useintentos.com"
+    }
+  }
+}
+```
+
+#### Cline / Continue / other MCP clients
+
+The config format is the same — `command`, `args`, `env`. Consult your client's docs for where the config file lives.
+
+### 4. Verify
+
+In a chat: *"Use IntentOS to find what kind of coffee I like and suggest a similar bean."*
+
+The agent should call `query_preferences`, then `check_vendor_trust` on any vendor it suggests, and you'll see those calls in your **/dashboard/audit** log on IntentOS.
+
+## Environment variables
+
+| Var | Required | Default | Purpose |
+|---|---|---|---|
+| `INTENTOS_API_KEY` | yes | — | The `sk_intent_…` key from `/dashboard/agents` |
+| `INTENTOS_BASE_URL` | no | `https://useintentos.com` | Override if you self-host IntentOS at a different URL |
+
+## Security
+
+The API key is stored in your MCP client's config file (typically `~/.config/...`) and passed to the server as an env var. It never leaves your machine except to talk to your IntentOS deployment. The IntentOS server stores only a sha256 hash of the key — the plaintext is your responsibility.
+
+If a key is compromised: log into IntentOS, **/dashboard/agents** → trash icon to revoke, then issue a new key and update your MCP config.
+
+## Troubleshooting
+
+**Agent can't see the tools / "intentos" not listed**: Make sure your config JSON is valid (mcpServers is the top-level key). Restart the MCP client fully — Claude Desktop in particular caches mcp configs.
+
+**"INTENTOS_API_KEY is not set"**: The env var isn't reaching the subprocess. Double-check the `env` block in your config; on Windows make sure paths are forward-slashed or properly escaped.
+
+**`401 invalid_api_key`**: Key was revoked or has a typo. Check `/dashboard/agents` and reissue if needed.
+
+**`403 scope_required`**: The agent's API key doesn't have the scope it needs. Reissue with broader scopes (e.g. add `query:semantic` if `query_preferences` returns 403).
+
+## License
+
+MIT.

package/dist/index.js

@@ -0,0 +1,188 @@
+#!/usr/bin/env node
+//
+// IntentOS MCP Server
+//
+// Exposes the IntentOS REST API to any MCP-compatible AI client (Claude
+// Desktop, Cursor, Cline, Continue, etc.) so the agent can read the user's
+// personal preference ledger before answering taste-sensitive questions.
+//
+// Configure via env vars:
+//   INTENTOS_API_KEY   — required, sk_intent_… from /dashboard/agents
+//   INTENTOS_BASE_URL  — optional, defaults to https://useintentos.com
+//
+// Usage with Claude Desktop, claude_desktop_config.json:
+//   {
+//     "mcpServers": {
+//       "intentos": {
+//         "command": "node",
+//         "args": ["/absolute/path/to/intentos/mcp/dist/index.js"],
+//         "env": {
+//           "INTENTOS_API_KEY": "sk_intent_..."
+//         }
+//       }
+//     }
+//   }
+import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
+import { z } from "zod";
+const API_KEY = process.env.INTENTOS_API_KEY?.trim();
+const BASE_URL = (process.env.INTENTOS_BASE_URL ?? "https://useintentos.com").replace(/\/+$/, "");
+if (!API_KEY) {
+    console.error("intentos-mcp: INTENTOS_API_KEY is not set. Issue a key at " +
+        `${BASE_URL}/dashboard/agents and pass it via the MCP client's env config.`);
+    process.exit(1);
+}
+// ── HTTP helpers ──────────────────────────────────────────────────────────
+async function intentosRequest(path, init = {}) {
+    const res = await fetch(`${BASE_URL}${path}`, {
+        ...init,
+        headers: {
+            Authorization: `Bearer ${API_KEY}`,
+            "Content-Type": "application/json",
+            ...(init.headers ?? {}),
+        },
+    });
+    if (!res.ok) {
+        const body = await res.text().catch(() => "");
+        throw new Error(`IntentOS ${res.status}: ${body || res.statusText}`);
+    }
+    return (await res.json());
+}
+function asTextResult(payload) {
+    return {
+        content: [
+            {
+                type: "text",
+                text: typeof payload === "string" ? payload : JSON.stringify(payload, null, 2),
+            },
+        ],
+    };
+}
+// ── Server ────────────────────────────────────────────────────────────────
+const server = new McpServer({
+    name: "intentos",
+    version: "1.0.0",
+});
+// 1) Semantic search across the ledger
+server.tool("query_preferences", "Semantic search across the user's IntentOS ledger. Use this whenever the user is making a decision in a domain where their stored preferences might apply (shopping, travel, recommendations, food, gear, etc.). Returns matching preferences with similarity scores; filter by sentiment to separate things they love (positive) from things they avoid (negative). Always cite their preferences when explaining recommendations.", {
+    query: z
+        .string()
+        .min(1)
+        .describe("Natural-language question to match against the user's preferences. e.g. 'what kind of coffee do I drink', 'restaurants I avoid', 'travel mistakes'."),
+    k: z
+        .number()
+        .int()
+        .min(1)
+        .max(40)
+        .optional()
+        .describe("Maximum matches to return. Default 8."),
+    min_similarity: z
+        .number()
+        .min(0)
+        .max(1)
+        .optional()
+        .describe("Cosine-similarity threshold between 0 and 1. Default 0.5. Lower for more recall, higher for precision."),
+    category: z
+        .string()
+        .optional()
+        .describe("Optional category slug to scope the query (e.g. 'coffee', 'headphones')."),
+}, async ({ query, k, min_similarity, category }) => {
+    const data = await intentosRequest("/api/v1/query", {
+        method: "POST",
+        body: JSON.stringify({ query, k, min_similarity, category }),
+    });
+    return asTextResult(data);
+});
+// 2) Read a full category
+server.tool("get_category", "Read everything the user has captured in a specific preference category — structured fields, positive examples, negative examples. Use when the user has named a domain (e.g. 'help me pick coffee' → category: 'coffee'). Prefer this over query_preferences when you already know the category, since it's authoritative rather than similarity-based.", {
+    slug: z
+        .string()
+        .min(1)
+        .describe("The category slug as stored in IntentOS (lowercase, hyphenated). e.g. 'coffee', 'home-cooking', 'travel'."),
+}, async ({ slug }) => {
+    const data = await intentosRequest(`/api/v1/preferences/${encodeURIComponent(slug)}`);
+    return asTextResult(data);
+});
+// 3) Trust lookup on a vendor
+server.tool("check_vendor_trust", "Look up whether the user has flagged a specific vendor as trusted or distrusted, with their stated reason and a numeric trust score (0-100). ALWAYS call this before recommending a specific brand or merchant — distrusted vendors should be avoided, trusted ones can be cited as a reason.", {
+    vendor: z
+        .string()
+        .min(1)
+        .describe("Brand or merchant name. e.g. 'Sennheiser', 'Starbucks Reserve'."),
+}, async ({ vendor }) => {
+    const data = await intentosRequest(`/api/v1/trust/${encodeURIComponent(vendor)}`);
+    return asTextResult(data);
+});
+// 4) Add new preferences (write — requires *:write scope on the API key)
+server.tool("add_preferences", "Append new preferences to a category — useful when the user explicitly says 'remember that I…' or after they've confirmed a recommendation worked or failed. Requires the agent's API key to have the appropriate write scope (preferences:write or {category}:write). Use sparingly and only when the user clearly wants something persisted.", {
+    category: z
+        .string()
+        .min(1)
+        .describe("Category slug to append to. Must already exist in the ledger."),
+    positive_examples: z
+        .array(z.object({
+        label: z
+            .string()
+            .min(1)
+            .describe("Short label (e.g. 'Sennheiser HD600s')."),
+        detail: z.string().optional(),
+        tags: z.array(z.string()).optional(),
+    }))
+        .optional()
+        .describe("Things the user likes."),
+    negative_examples: z
+        .array(z.object({
+        label: z.string().min(1),
+        detail: z.string().optional(),
+        tags: z.array(z.string()).optional(),
+    }))
+        .optional()
+        .describe("Things the user dislikes or avoids."),
+    outcome: z
+        .object({
+        vendor: z.string().min(1),
+        product: z.string().min(1),
+        result: z.enum(["success", "partial", "failure"]),
+        rating: z.number().int().min(1).max(5).optional(),
+        price_cents: z.number().int().min(0).optional(),
+        notes: z.string().optional(),
+    })
+        .optional()
+        .describe("Optional purchase outcome — record that a specific product from a vendor worked, partially worked, or failed."),
+}, async ({ category, ...body }) => {
+    const data = await intentosRequest(`/api/v1/preferences/${encodeURIComponent(category)}/update`, {
+        method: "POST",
+        body: JSON.stringify(body),
+    });
+    return asTextResult(data);
+});
+// 5) Self-report what the agent did with the data
+server.tool("record_audit_event", "Optionally record what you did with the user's preferences — useful when an agent acts on retrieved data (e.g. 'used trust ledger to reject vendor X', 'recommended product Y based on category Z'). Helps the user see the full chain in their /dashboard/audit log.", {
+    endpoint: z
+        .string()
+        .min(1)
+        .describe("Logical endpoint or action name. e.g. 'recommendation/coffee', 'reject/vendor'."),
+    scope: z.string().optional(),
+    query: z.string().optional().describe("Original user prompt that triggered this."),
+    result_summary: z
+        .string()
+        .optional()
+        .describe("One-line summary of what you did."),
+    metadata: z.record(z.string(), z.unknown()).optional(),
+}, async (body) => {
+    const data = await intentosRequest("/api/v1/audit", {
+        method: "POST",
+        body: JSON.stringify(body),
+    });
+    return asTextResult(data);
+});
+// ── Boot ──────────────────────────────────────────────────────────────────
+async function main() {
+    const transport = new StdioServerTransport();
+    await server.connect(transport);
+    console.error(`intentos-mcp connected to ${BASE_URL} — ready to serve preference reads.`);
+}
+main().catch((err) => {
+    console.error("intentos-mcp fatal error:", err);
+    process.exit(1);
+});

package/package.json

@@ -0,0 +1,29 @@
+{
+  "name": "intentos-mcp",
+  "version": "1.0.0",
+  "description": "MCP server for IntentOS — exposes a personal preference ledger to any MCP-compatible AI client (Claude Desktop, Cursor, Cline, Continue, etc.)",
+  "type": "module",
+  "bin": {
+    "intentos-mcp": "dist/index.js"
+  },
+  "main": "dist/index.js",
+  "files": [
+    "dist",
+    "README.md"
+  ],
+  "scripts": {
+    "build": "tsc",
+    "start": "node dist/index.js",
+    "dev": "tsc --watch"
+  },
+  "keywords": ["mcp", "intentos", "agents", "preferences"],
+  "license": "MIT",
+  "dependencies": {
+    "@modelcontextprotocol/sdk": "^1.0.4",
+    "zod": "^3.24.1"
+  },
+  "devDependencies": {
+    "@types/node": "^22.10.2",
+    "typescript": "^5.7.2"
+  }
+}