@live-context/mcp 0.3.0

package/README.md

@@ -0,0 +1,47 @@
+# @live-context/mcp
+
+Stdio MCP proxy for [Live Context](https://live-context.com) — your team's shared AI knowledge layer. This package is a thin client that forwards MCP tool calls to the hosted API at `live-context.com/api/mcp/*`. It does not connect to any database directly. The only thing your machine needs is an MCP API key.
+
+## Install
+
+The fastest path is the dashboard's one-liner. After signing in at [live-context.com](https://live-context.com), go to **Settings → MCP**, copy your key, and run:
+
+```bash
+claude mcp add live-context -e MCP_API_KEY=<your-key> -- npx -y @live-context/mcp
+```
+
+Restart Claude Code. Live Context is now wired in.
+
+## Manual configuration
+
+For Claude Desktop, Cursor, or any other MCP client, add this to your `mcpServers` config:
+
+```json
+{
+  "mcpServers": {
+    "live-context": {
+      "command": "npx",
+      "args": ["-y", "@live-context/mcp"],
+      "env": {
+        "MCP_API_KEY": "<your-key>"
+      }
+    }
+  }
+}
+```
+
+## Environment variables
+
+| Variable | Required | Purpose |
+| --- | --- | --- |
+| `MCP_API_KEY` | yes | Your team's `lc_team_…` key from Settings → MCP. |
+| `LC_USER_TOKEN` | no | Personal token for notebook-scoped reads/writes. |
+| `LC_API_BASE_URL` | no | Override the API base. Defaults to `https://live-context.com`. |
+
+## Tools
+
+`get_context`, `list_spaces`, `list_collections`, `list_notebooks`, `list_context`, `write_context`, `health_check`. See the [Live Context docs](https://live-context.com/docs) for usage.
+
+## Get a key
+
+[live-context.com/dashboard/settings/mcp](https://live-context.com/dashboard/settings/mcp)

package/dist/index.d.ts

@@ -0,0 +1,22 @@
+#!/usr/bin/env node
+/**
+ * Live Context MCP — stdio proxy to the hosted HTTP API.
+ *
+ * Phase 5 Wave 5 design pivot: the MCP server no longer talks to Supabase
+ * directly. It's a thin stdio-to-HTTP translator. All data work happens at
+ * https://live-context.com/api/mcp/* server-side. Customer-side: only one
+ * required env var (MCP_API_KEY); no Supabase keys ever cross the wire.
+ *
+ * Required environment variables:
+ *   MCP_API_KEY        — The team's mcp_api_key (lc_team_*) value
+ *
+ * Optional:
+ *   LC_USER_TOKEN      — Personal API token from /dashboard/settings/mcp
+ *                        (required for notebook-scoped operations)
+ *   LC_API_BASE_URL    — Override the API base URL (default: production).
+ *                        Useful for staging / local development.
+ *
+ * Transport: StdioServerTransport (Claude Code, Cursor, Claude Desktop).
+ * Usage:     `npx -y @live-context/mcp` (after publishing).
+ */
+export {};

package/dist/index.js

@@ -0,0 +1,197 @@
+#!/usr/bin/env node
+/**
+ * Live Context MCP — stdio proxy to the hosted HTTP API.
+ *
+ * Phase 5 Wave 5 design pivot: the MCP server no longer talks to Supabase
+ * directly. It's a thin stdio-to-HTTP translator. All data work happens at
+ * https://live-context.com/api/mcp/* server-side. Customer-side: only one
+ * required env var (MCP_API_KEY); no Supabase keys ever cross the wire.
+ *
+ * Required environment variables:
+ *   MCP_API_KEY        — The team's mcp_api_key (lc_team_*) value
+ *
+ * Optional:
+ *   LC_USER_TOKEN      — Personal API token from /dashboard/settings/mcp
+ *                        (required for notebook-scoped operations)
+ *   LC_API_BASE_URL    — Override the API base URL (default: production).
+ *                        Useful for staging / local development.
+ *
+ * Transport: StdioServerTransport (Claude Code, Cursor, Claude Desktop).
+ * Usage:     `npx -y @live-context/mcp` (after publishing).
+ */
+import { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
+import { StdioServerTransport } from '@modelcontextprotocol/sdk/server/stdio.js';
+import { z } from 'zod';
+// ---------------------------------------------------------------------------
+// Config
+// ---------------------------------------------------------------------------
+const MCP_API_KEY = process.env.MCP_API_KEY ?? '';
+const LC_USER_TOKEN = process.env.LC_USER_TOKEN ?? null;
+const API_BASE_URL = process.env.LC_API_BASE_URL?.replace(/\/$/, '') ?? 'https://live-context.com';
+if (!MCP_API_KEY) {
+    console.error('[mcp] MCP_API_KEY is not set — tools will fail with auth errors');
+}
+async function callMcpApi(tool, args, method = 'POST') {
+    const url = `${API_BASE_URL}/api/mcp/${tool}`;
+    const headers = {
+        Authorization: `Bearer ${MCP_API_KEY}`,
+        'Content-Type': 'application/json',
+    };
+    if (LC_USER_TOKEN) {
+        headers['X-LC-User-Token'] = LC_USER_TOKEN;
+    }
+    try {
+        const response = await fetch(url, {
+            method,
+            headers,
+            body: method === 'POST' ? JSON.stringify({ args }) : undefined,
+        });
+        if (!response.ok) {
+            const errBody = (await response.json().catch(() => ({})));
+            return {
+                content: [
+                    {
+                        type: 'text',
+                        text: JSON.stringify({
+                            error: errBody.error ?? 'http_error',
+                            message: errBody.message ?? `HTTP ${response.status}`,
+                            status: response.status,
+                        }),
+                    },
+                ],
+            };
+        }
+        const json = (await response.json());
+        // health_check returns a plain object; tools return McpToolResult shape.
+        if ('content' in json && Array.isArray(json.content)) {
+            return json;
+        }
+        return {
+            content: [{ type: 'text', text: JSON.stringify(json) }],
+        };
+    }
+    catch (err) {
+        return {
+            content: [
+                {
+                    type: 'text',
+                    text: JSON.stringify({
+                        error: 'network_error',
+                        message: err.message,
+                    }),
+                },
+            ],
+        };
+    }
+}
+// ---------------------------------------------------------------------------
+// Server definition — schemas mirror the v1 tool surface; handlers are HTTP
+// proxies. zod schemas stay client-side because the MCP protocol expects them
+// in the tool registration; the hosted API also re-validates server-side.
+// ---------------------------------------------------------------------------
+const server = new McpServer({
+    name: 'live-context-mcp',
+    version: '0.3.0', // bumped for Wave 5 hosted-proxy rewrite
+});
+server.registerTool('get_context', {
+    description: 'Retrieve relevant context entries. Returns L0 summaries (title, type, snippet) by default. Pass drawer_id to get full page body.',
+    inputSchema: {
+        query: z.string().optional().describe('Search query. Omit for L0 init summary.'),
+        limit: z.number().int().positive().max(10).optional().describe('Max results (default 10, max 10)'),
+        space: z.string().optional().describe('Filter by Space name'),
+        notebook: z.string().optional().describe('Filter by Notebook name (requires user token)'),
+        scope: z
+            .enum(['team', 'personal', 'all'])
+            .optional()
+            .describe('Search scope: team, personal, or all (default)'),
+        drawer_id: z
+            .string()
+            .optional()
+            .describe('Page ID to retrieve full body (drill-down from L0 result)'),
+        type: z
+            .string()
+            .optional()
+            .describe('Filter by knowledge type (decision, constraint, pattern, entity, open_question, event, preference)'),
+    },
+}, (args) => callMcpApi('get-context', args));
+server.registerTool('list_spaces', {
+    description: 'List all knowledge Spaces available to the team',
+    inputSchema: {
+        include_page_counts: z.boolean().optional().describe('Include published page counts per Space'),
+        include_shared: z.boolean().optional().describe('Include Spaces shared with this team (read-only)'),
+    },
+}, (args) => callMcpApi('list-spaces', args));
+server.registerTool('list_collections', {
+    description: 'List Collections within a Space or Notebook',
+    inputSchema: {
+        space_id: z.string().optional().describe('Space ID to list collections for'),
+        notebook_id: z.string().optional().describe('Notebook ID to list collections for'),
+        include_page_counts: z.boolean().optional().describe('Include published page counts per Collection'),
+    },
+}, (args) => callMcpApi('list-collections', args));
+server.registerTool('list_notebooks', {
+    description: 'List your personal Notebooks (requires user token)',
+    inputSchema: {},
+}, () => callMcpApi('list-notebooks', {}));
+server.registerTool('list_context', {
+    description: 'Paginated listing of all context entries for the team',
+    inputSchema: {
+        page: z.number().int().positive().optional().describe('Page number (1-indexed)'),
+        per_page: z.number().int().positive().optional().describe('Results per page'),
+        type: z.string().optional().describe('Filter by knowledge type'),
+        space: z.string().optional().describe('Filter by Space name'),
+        notebook: z.string().optional().describe('Filter by Notebook name'),
+    },
+}, (args) => callMcpApi('list-context', args));
+server.registerTool('write_context', {
+    description: `Save team or personal knowledge to Live Context. Routes to a Space (team) or Notebook (personal) based on scope.
+
+IMPORTANT — Structure the content field using clear type signals so it classifies accurately:
+- Decisions: Include "we chose/decided/evaluated" + alternatives considered + reasoning.
+- Constraints: Use mandate language — "must", "must not", "never", "always", "required".
+- Patterns: Describe reusable steps — "The pattern for X is: (1)... (2)... (3)...".
+- Entities: Define what something IS — "X is...", "X refers to...", "There are N types of X".
+- Events: Lead with a specific date — "On YYYY-MM-DD, [what happened]".
+- Open questions: Frame as an explicit unresolved question — "Should we...?", "Unresolved: ...".
+- Preferences: First-person only — "I prefer", "I use", "my approach".
+
+DO NOT write content that restates code, git history, or existing drawers. Call list_context or get_context first if unsure — update beats duplicate.
+
+When migrating from an existing doc, set the source field to the relative file path so provenance is preserved.
+
+If you know the knowledge type, pass it in type_hint for higher classification accuracy.`,
+    inputSchema: {
+        content: z.string().describe('The knowledge content with clear type signals.'),
+        type_hint: z
+            .enum(['decision', 'constraint', 'pattern', 'entity', 'open_question', 'event', 'preference'])
+            .optional()
+            .describe('Optional knowledge type hint. Provide when obvious.'),
+        scope: z.enum(['team', 'personal']).optional().describe('Routing scope: team (default) or personal (requires user token)'),
+        space: z.string().optional().describe('Target Space name (team scope)'),
+        notebook: z.string().optional().describe('Target Notebook name (personal scope)'),
+        source: z.string().optional().describe('Origin source identifier. For doc migrations, the relative file path.'),
+        metadata: z.record(z.string(), z.unknown()).optional().describe('Arbitrary metadata key/value pairs'),
+    },
+}, (args) => callMcpApi('write-context', args));
+server.registerTool('health_check', {
+    description: 'Returns server health status and resolved team identity',
+}, () => callMcpApi('health-check', undefined, 'GET'));
+// ---------------------------------------------------------------------------
+// Process-level error handlers
+// ---------------------------------------------------------------------------
+process.on('unhandledRejection', (reason) => {
+    console.error('[mcp] UNHANDLED REJECTION:', reason);
+    process.exit(1);
+});
+process.on('uncaughtException', (err) => {
+    console.error('[mcp] UNCAUGHT EXCEPTION:', err);
+    process.exit(1);
+});
+// ---------------------------------------------------------------------------
+// Start
+// ---------------------------------------------------------------------------
+async function start() {
+    const transport = new StdioServerTransport();
+    await server.connect(transport);
+}
+start();

package/package.json

@@ -0,0 +1,31 @@
+{
+  "name": "@live-context/mcp",
+  "version": "0.3.0",
+  "private": false,
+  "description": "Live Context MCP — stdio proxy to live-context.com hosted API. Customer-side has no Supabase dependency.",
+  "type": "module",
+  "bin": {
+    "live-context-mcp": "dist/index.js"
+  },
+  "files": [
+    "dist",
+    "README.md"
+  ],
+  "scripts": {
+    "dev": "tsx index.ts",
+    "start": "node dist/index.js",
+    "build": "tsc"
+  },
+  "dependencies": {
+    "@modelcontextprotocol/sdk": "^1.15.0",
+    "zod": "^3.23.8"
+  },
+  "devDependencies": {
+    "@types/node": "^25.5.2",
+    "tsx": "^4.19.0",
+    "typescript": "^6.0.2"
+  },
+  "engines": {
+    "node": ">=18.0.0"
+  }
+}