@harkenai/mcp-server 0.1.0

package/README.md

@@ -0,0 +1,98 @@
+# @harkenai/mcp-server
+
+Model Context Protocol server for HarkenAI. Gives Claude Desktop, Cursor,
+Claude Code, or any MCP-aware host direct access to your HarkenAI
+sessions, transcripts, and contacts — no glue code, no scraping.
+
+## Install
+
+Issue an API key from **Settings → API Keys** in the HarkenAI web app.
+Copy the secret (`hkn_…`) — you'll only see it once.
+
+You don't need to install the package globally — most MCP hosts will
+spawn it via `npx`. The example configs below all use that pattern.
+
+## Wire it up
+
+### Claude Desktop
+
+Add to `~/Library/Application Support/Claude/claude_desktop_config.json`
+(macOS) or `%APPDATA%/Claude/claude_desktop_config.json` (Windows):
+
+```json
+{
+  "mcpServers": {
+    "harkenai": {
+      "command": "npx",
+      "args": ["-y", "@harkenai/mcp-server"],
+      "env": {
+        "HARKENAI_API_KEY": "hkn_..."
+      }
+    }
+  }
+}
+```
+
+Restart Claude Desktop. The HarkenAI tools appear in the tool tray.
+
+### Cursor
+
+Add to `~/.cursor/mcp.json`:
+
+```json
+{
+  "mcpServers": {
+    "harkenai": {
+      "command": "npx",
+      "args": ["-y", "@harkenai/mcp-server"],
+      "env": {
+        "HARKENAI_API_KEY": "hkn_..."
+      }
+    }
+  }
+}
+```
+
+### Claude Code
+
+```bash
+claude mcp add harkenai \
+  --env HARKENAI_API_KEY=hkn_... \
+  -- npx -y @harkenai/mcp-server
+```
+
+## Tools
+
+| Tool                        | Purpose                                                                 |
+|-----------------------------|-------------------------------------------------------------------------|
+| `harken.search_sessions`    | Paginated session list. Filters: `q`, `since`, `until`, `tag`, `personName`. |
+| `harken.get_session`        | Full payload for one session (summary, insights, action items, etc.).   |
+| `harken.get_transcript`     | Transcript text or JSON for one session. `format=text` is ideal for LLMs. |
+| `harken.list_recent`        | Shorthand: sessions from the last N days.                               |
+| `harken.search_contacts`    | Search contacts by name / company.                                      |
+
+## Environment
+
+| Variable             | Required | Default                                | Notes                              |
+|----------------------|----------|----------------------------------------|------------------------------------|
+| `HARKENAI_API_KEY`   | yes      | —                                      | Issue from Settings → API Keys.    |
+| `HARKENAI_API_URL`   | no       | `https://harkenai-api.onrender.com`    | Override for staging / self-hosted. |
+
+## Common prompts
+
+Once the server is registered, try asking the host:
+
+> "Summarize my conversations from last week using HarkenAI."
+>
+> "What did Alice and I discuss about pricing? Pull the transcript and
+>  quote the relevant lines."
+>
+> "List every session where 'compliance' was mentioned and give me the
+>  action items."
+
+Each of those drives `harken.list_recent` / `harken.search_sessions`
+plus `harken.get_transcript` under the hood.
+
+## License
+
+MIT

package/package.json

@@ -0,0 +1,41 @@
+{
+  "name": "@harkenai/mcp-server",
+  "version": "0.1.0",
+  "description": "Model Context Protocol server for HarkenAI — gives Claude / Cursor / Claude Desktop direct access to your sessions, transcripts, and contacts via the HarkenAI Developer API.",
+  "type": "module",
+  "bin": {
+    "harkenai-mcp": "src/index.js"
+  },
+  "files": [
+    "src",
+    "README.md"
+  ],
+  "scripts": {
+    "start": "node src/index.js"
+  },
+  "engines": {
+    "node": ">=18"
+  },
+  "keywords": [
+    "mcp",
+    "model-context-protocol",
+    "harkenai",
+    "claude"
+  ],
+  "license": "MIT",
+  "homepage": "https://harkenai.com",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/pbrosen/harkenai.git",
+    "directory": "mcp-server"
+  },
+  "bugs": {
+    "url": "https://github.com/pbrosen/harkenai/issues"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "dependencies": {
+    "@modelcontextprotocol/sdk": "^1.0.4"
+  }
+}

package/src/index.js

@@ -0,0 +1,213 @@
+#!/usr/bin/env node
+/**
+ * HarkenAI MCP server.
+ *
+ * Speaks the Model Context Protocol over stdio. Agents using Claude
+ * Desktop / Cursor / Claude Code can register this server with one
+ * config line and then call HarkenAI tools from any chat — no glue
+ * code required.
+ *
+ * Auth: HARKENAI_API_KEY env var (issued from Settings → API Keys in
+ * the HarkenAI web app). Optional HARKENAI_API_URL overrides the base
+ * URL — defaults to production.
+ *
+ * Tools exposed:
+ *   harken.search_sessions   filter + paginate sessions
+ *   harken.get_session       full payload for one session
+ *   harken.get_transcript    transcript text / JSON for one session
+ *   harken.list_recent       shorthand for "last N days"
+ *   harken.search_contacts   contacts by name / company
+ */
+
+import { Server } from '@modelcontextprotocol/sdk/server/index.js';
+import { StdioServerTransport } from '@modelcontextprotocol/sdk/server/stdio.js';
+import {
+  CallToolRequestSchema,
+  ListToolsRequestSchema,
+} from '@modelcontextprotocol/sdk/types.js';
+
+const API_URL = (process.env.HARKENAI_API_URL || 'https://harkenai-api.onrender.com').replace(/\/$/, '');
+const RAW_API_KEY = process.env.HARKENAI_API_KEY || '';
+// Trim defensively. The #1 cause of 401s here is a stray trailing newline
+// or leading whitespace in the host's config — Claude Desktop / Cursor
+// JSON-encode the env var literally, so any whitespace the user pasted
+// rides along into the Authorization header and the server rejects it.
+const API_KEY = RAW_API_KEY.trim();
+
+if (!API_KEY) {
+  console.error('[harkenai-mcp] HARKENAI_API_KEY is not set. Issue a key in Settings → API Keys.');
+  process.exit(2);
+}
+if (RAW_API_KEY !== API_KEY) {
+  console.error('[harkenai-mcp] WARNING: HARKENAI_API_KEY had surrounding whitespace; trimmed before use.');
+}
+if (!API_KEY.startsWith('hkn_')) {
+  console.error(`[harkenai-mcp] WARNING: HARKENAI_API_KEY does not start with "hkn_". Got prefix: ${API_KEY.slice(0, 6)}…`);
+}
+console.error(`[harkenai-mcp] starting against ${API_URL} with key ${API_KEY.slice(0, 12)}… (${API_KEY.length} chars)`);
+
+async function call(endpoint, init = {}) {
+  const url = `${API_URL}${endpoint}`;
+  const res = await fetch(url, {
+    ...init,
+    headers: {
+      Authorization: `Bearer ${API_KEY}`,
+      'Content-Type': 'application/json',
+      ...(init.headers || {}),
+    },
+  });
+  if (!res.ok) {
+    const text = await res.text().catch(() => '');
+    // Log the failing URL + status to stderr so users can see it in
+    // ~/Library/Logs/Claude/mcp-server-harkenai.log (or equivalent) when
+    // a tool call mysteriously fails.
+    console.error(`[harkenai-mcp] ${init.method || 'GET'} ${endpoint} -> ${res.status} ${res.statusText}`);
+    throw new Error(`HarkenAI API ${res.status}: ${text || res.statusText}`);
+  }
+  // Streamed responses (e.g. /transcripts) come back as text; the
+  // helpers below detect content-type and parse appropriately.
+  const ct = res.headers.get('content-type') || '';
+  if (ct.includes('application/json')) return res.json();
+  if (ct.includes('application/x-ndjson')) return res.text();
+  return res.text();
+}
+
+const TOOLS = [
+  {
+    name: 'harken.search_sessions',
+    description:
+      'Search HarkenAI sessions. Returns lightweight summaries (id, name, date, duration, peopleCount, tags, summary). Use harken.get_transcript next when you need the full text.',
+    inputSchema: {
+      type: 'object',
+      properties: {
+        q: { type: 'string', description: 'Full-text search across session content' },
+        since: {
+          type: 'string',
+          description: 'ISO date — only sessions updated on or after this',
+        },
+        until: { type: 'string', description: 'ISO date — only sessions updated on or before this' },
+        tag: { type: 'string', description: 'Filter by tag (comma-separated for OR)' },
+        personName: { type: 'string', description: 'Filter sessions that include this person' },
+        limit: { type: 'integer', minimum: 1, maximum: 100, default: 25 },
+        cursor: { type: 'string', description: 'updatedAt cursor from a previous page' },
+      },
+    },
+  },
+  {
+    name: 'harken.get_session',
+    description: 'Fetch the full payload (summary, insights, action items, conversations, contacts) for one session by id.',
+    inputSchema: {
+      type: 'object',
+      properties: { id: { type: 'string' } },
+      required: ['id'],
+    },
+  },
+  {
+    name: 'harken.get_transcript',
+    description:
+      'Fetch the transcript for one session. Defaults to plain text (speaker-prefixed) which is best for LLM consumption. Pass format=json for the structured payload including segments, speakerAssignments, and a `participants` array that joins each speaker to their Contact (name, role, company) — saving you a second call when you need titles or affiliations. Markdown output (format=markdown) starts with a "## Participants" block.',
+    inputSchema: {
+      type: 'object',
+      properties: {
+        id: { type: 'string' },
+        format: { type: 'string', enum: ['text', 'json', 'markdown'], default: 'text' },
+        withParticipants: { type: 'boolean', default: false, description: 'Only honored for format=text — when true, prepends a participants block to the plain-text body.' },
+      },
+      required: ['id'],
+    },
+  },
+  {
+    name: 'harken.list_recent',
+    description: 'List sessions from the last N days. Shorthand for search_sessions with a relative since= date.',
+    inputSchema: {
+      type: 'object',
+      properties: {
+        days: { type: 'integer', minimum: 1, maximum: 365, default: 7 },
+        limit: { type: 'integer', minimum: 1, maximum: 100, default: 25 },
+      },
+    },
+  },
+  {
+    name: 'harken.search_contacts',
+    description: 'Search contacts known to this HarkenAI user.',
+    inputSchema: {
+      type: 'object',
+      properties: {
+        q: { type: 'string' },
+        company: { type: 'string' },
+        limit: { type: 'integer', minimum: 1, maximum: 100, default: 25 },
+      },
+    },
+  },
+];
+
+function qs(params) {
+  const search = new URLSearchParams();
+  for (const [k, v] of Object.entries(params || {})) {
+    if (v === undefined || v === null || v === '') continue;
+    search.set(k, String(v));
+  }
+  const s = search.toString();
+  return s ? `?${s}` : '';
+}
+
+async function runTool(name, args) {
+  switch (name) {
+    case 'harken.search_sessions': {
+      const data = await call(`/api/v1/sessions${qs(args)}`);
+      return data;
+    }
+    case 'harken.get_session': {
+      if (!args?.id) throw new Error('id is required');
+      return call(`/api/v1/sessions/${encodeURIComponent(args.id)}`);
+    }
+    case 'harken.get_transcript': {
+      if (!args?.id) throw new Error('id is required');
+      const fmt = args.format === 'json' ? 'json'
+        : args.format === 'markdown' ? 'md'
+        : 'txt';
+      const params = { format: fmt };
+      if (fmt === 'txt' && args.withParticipants) params.withParticipants = 'true';
+      const path = `/api/v1/sessions/${encodeURIComponent(args.id)}/transcript${qs(params)}`;
+      const result = await call(path);
+      return typeof result === 'string' ? { text: result, format: fmt } : result;
+    }
+    case 'harken.list_recent': {
+      const days = Math.min(Math.max(Number(args?.days) || 7, 1), 365);
+      const since = new Date(Date.now() - days * 24 * 60 * 60 * 1000).toISOString();
+      return call(`/api/v1/sessions${qs({ since, limit: args?.limit || 25 })}`);
+    }
+    case 'harken.search_contacts': {
+      return call(`/api/v1/contacts${qs(args)}`);
+    }
+    default:
+      throw new Error(`Unknown tool: ${name}`);
+  }
+}
+
+const server = new Server(
+  { name: 'harkenai-mcp', version: '0.1.0' },
+  { capabilities: { tools: {} } },
+);
+
+server.setRequestHandler(ListToolsRequestSchema, async () => ({ tools: TOOLS }));
+
+server.setRequestHandler(CallToolRequestSchema, async (req) => {
+  const { name, arguments: args } = req.params;
+  try {
+    const result = await runTool(name, args || {});
+    const payload = typeof result === 'string' ? result : JSON.stringify(result, null, 2);
+    return {
+      content: [{ type: 'text', text: payload }],
+    };
+  } catch (err) {
+    return {
+      isError: true,
+      content: [{ type: 'text', text: `Error: ${err.message}` }],
+    };
+  }
+});
+
+const transport = new StdioServerTransport();
+await server.connect(transport);
+console.error('[harkenai-mcp] connected. Waiting for tool calls…');