@kanecta/mcp 1.0.0

package/README.md

@@ -0,0 +1,129 @@
+# @kanecta/mcp
+
+MCP (Model Context Protocol) server for [Kanecta](https://github.com/cloudsculptor/kanecta) — gives Claude direct, structured access to your personal knowledge base.
+
+Once installed, Claude can capture insights, search past context, and browse your knowledge base as native tools — no slash commands, no prompting required.
+
+---
+
+## Quick start
+
+### Install via Claude Code CLI (recommended)
+
+```bash
+claude mcp add --transport stdio kanecta -- npx -y @kanecta/mcp
+```
+
+### Install via Kanecta wizard
+
+If you have `@kanecta/claude` installed, the setup wizard handles this automatically:
+
+```bash
+kanecta claude wizard
+```
+
+### Install manually (Claude Desktop)
+
+Add to `~/Library/Application Support/Claude/claude_desktop_config.json` (macOS) or `%APPDATA%\Claude\claude_desktop_config.json` (Windows):
+
+```json
+{
+  "mcpServers": {
+    "kanecta": {
+      "command": "npx",
+      "args": ["-y", "@kanecta/mcp"],
+      "env": {
+        "KANECTA_DATASTORE": "/path/to/your/kanecta/datastore"
+      }
+    }
+  }
+}
+```
+
+### Install manually (Claude Code `settings.json`)
+
+Add to `~/.claude/settings.json`:
+
+```json
+{
+  "mcpServers": {
+    "kanecta": {
+      "command": "npx",
+      "args": ["-y", "@kanecta/mcp"],
+      "type": "stdio"
+    }
+  }
+}
+```
+
+---
+
+## Datastore discovery
+
+The server resolves the datastore path in this order:
+
+1. `KANECTA_DATASTORE` environment variable
+2. `~/.kanecta-config.json` → `datastorePath` (set by `kanecta claude wizard`)
+3. Default: `~/.kanecta/`
+
+---
+
+## Tools
+
+| Tool | Description |
+|------|-------------|
+| `kanecta_capture` | Save context, decisions, or insights. Never accepts secrets. |
+| `kanecta_search` | Full-text substring search across all items. |
+| `kanecta_recent` | List the most recent captures. |
+| `kanecta_get` | Fetch a specific item by UUID. |
+| `kanecta_get_children` | List children of an item (omit `parentId` for roots). |
+| `kanecta_get_tree` | Get an item with its subtree expanded to a given depth. |
+| `kanecta_add_item` | Add an item with explicit placement in the hierarchy. |
+| `kanecta_update_item` | Update an item's value or type. |
+| `kanecta_delete_item` | Delete an item (pass `force: true` to override backlink check). |
+
+---
+
+## How captures are organised
+
+Captures are grouped under date items (`YYYY-MM-DD`) in the hierarchy:
+
+```
+Claude Captures
+└── 2025-05-16
+    ├── "Decided to use PostgreSQL for the sessions table"
+    └── "Auth middleware rewrite is driven by compliance, not tech debt"
+└── 2025-05-15
+    └── "Merge freeze begins 2025-05-22 for mobile release"
+```
+
+`kanecta_recent` returns the most recent captures sorted by date then insertion order.
+
+---
+
+## Secret protection
+
+`kanecta_capture` refuses to store content that matches known secret patterns (API keys, tokens, private keys, passwords). This runs client-side — nothing is sent to any external service.
+
+---
+
+## Requirements
+
+- Node.js ≥ 18
+- A Kanecta datastore (created by `kanecta claude wizard` or `@kanecta/lib`)
+
+---
+
+## Checking server status
+
+Inside a Claude Code session:
+
+```
+/mcp
+```
+
+---
+
+## License
+
+MIT

package/package.json

@@ -0,0 +1,41 @@
+{
+  "name": "@kanecta/mcp",
+  "version": "1.0.0",
+  "description": "Kanecta MCP server — gives Claude direct access to your personal knowledge base",
+  "main": "src/index.js",
+  "bin": {
+    "kanecta-mcp": "src/index.js"
+  },
+  "scripts": {
+    "start": "node src/index.js",
+    "release": "bash scripts/release.sh",
+    "release:minor": "bash scripts/release.sh minor",
+    "release:major": "bash scripts/release.sh major"
+  },
+  "files": [
+    "src/",
+    "scripts/"
+  ],
+  "engines": {
+    "node": ">=18.0.0"
+  },
+  "dependencies": {
+    "@kanecta/lib": "^1.0.0"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "keywords": [
+    "kanecta",
+    "mcp",
+    "model-context-protocol",
+    "claude",
+    "claude-code",
+    "knowledge-base",
+    "personal-memory",
+    "ai",
+    "notes"
+  ],
+  "author": "Richie Thomas <richardsempire@gmail.com>",
+  "license": "MIT"
+}

package/scripts/release.sh

@@ -0,0 +1,36 @@
+#!/usr/bin/env bash
+set -euo pipefail
+
+BUMP=${1:-patch}
+
+if [[ "$BUMP" != "patch" && "$BUMP" != "minor" && "$BUMP" != "major" ]]; then
+  echo "Usage: npm run release [-- patch|minor|major]  (default: patch)"
+  exit 1
+fi
+
+cd "$(dirname "$0")/.."
+
+echo "==> Checking for uncommitted changes..."
+if ! git diff --quiet || ! git diff --cached --quiet; then
+  echo "Error: uncommitted changes detected. Commit or stash them first."
+  exit 1
+fi
+
+echo "==> Checking npm auth..."
+if ! npm whoami &>/dev/null; then
+  echo "Error: not logged in to npm. Run: npm login"
+  exit 1
+fi
+
+echo "==> Bumping $BUMP version..."
+npm version "$BUMP" --message "chore(kanecta-mcp): release v%s"
+
+echo "==> Publishing to npm..."
+npm publish --access public
+
+echo "==> Pushing commit and tag..."
+git push --follow-tags
+
+NEW_VERSION=$(node -p "require('./package.json').version")
+echo ""
+echo "Released @kanecta/mcp v$NEW_VERSION"

package/src/index.js

@@ -0,0 +1,339 @@
+#!/usr/bin/env node
+'use strict';
+
+const os = require('os');
+const fs = require('fs');
+const path = require('path');
+const { KanectaConnector } = require('@kanecta/lib');
+const { walkDataDir } = require('@kanecta/lib/src/datastore');
+
+// ─── Config ───────────────────────────────────────────────────────────────────
+
+const CONFIG_PATH = path.join(os.homedir(), '.kanecta-config.json');
+const DEFAULT_DATASTORE_PATH = path.join(os.homedir(), '.kanecta');
+
+function readConfig() {
+  try { return JSON.parse(fs.readFileSync(CONFIG_PATH, 'utf8')); } catch { return null; }
+}
+
+function writeConfig(cfg) {
+  fs.writeFileSync(CONFIG_PATH, JSON.stringify(cfg, null, 2) + '\n');
+}
+
+function getDatastorePath() {
+  if (process.env.KANECTA_DATASTORE) {
+    return process.env.KANECTA_DATASTORE.replace(/^~/, os.homedir());
+  }
+  const cfg = readConfig();
+  if (cfg && cfg.datastorePath) return cfg.datastorePath.replace(/^~/, os.homedir());
+  return DEFAULT_DATASTORE_PATH;
+}
+
+// ─── Secret detection ─────────────────────────────────────────────────────────
+
+const SECRET_PATTERNS = [
+  { name: 'Anthropic API key', re: /sk-ant-[a-zA-Z0-9_-]{20,}/ },
+  { name: 'OpenAI API key', re: /sk-[a-zA-Z0-9]{20,}/ },
+  { name: 'AWS access key', re: /AKIA[0-9A-Z]{16}/ },
+  { name: 'GitHub token', re: /gh[psoure]_[a-zA-Z0-9]{36,}/ },
+  { name: 'JWT', re: /eyJ[a-zA-Z0-9_-]{10,}\.[a-zA-Z0-9_-]{10,}\.[a-zA-Z0-9_-]{10,}/ },
+  { name: 'private key', re: /-----BEGIN [A-Z ]+ PRIVATE KEY-----/ },
+  { name: 'secret/password field', re: /(password|passwd|secret|api[_-]?key|private[_-]?key|access[_-]?token)\s*[=:]\s*\S{8,}/i },
+];
+
+function detectSecrets(text) {
+  if (!text || typeof text !== 'string') return [];
+  return SECRET_PATTERNS.filter(({ re }) => re.test(text)).map(({ name }) => name);
+}
+
+// ─── Tools ────────────────────────────────────────────────────────────────────
+
+const TOOLS = [
+  {
+    name: 'kanecta_capture',
+    description: 'Save context, decisions, insights, or facts to the Kanecta knowledge base. Use for anything worth remembering across sessions. Never call this with secrets, API keys, passwords, or tokens.',
+    inputSchema: {
+      type: 'object',
+      properties: {
+        text: { type: 'string', description: 'The content to capture' },
+        type: { type: 'string', enum: ['text', 'string', 'decision'], description: 'Item type — defaults to "text"' },
+      },
+      required: ['text'],
+    },
+  },
+  {
+    name: 'kanecta_search',
+    description: 'Search the Kanecta knowledge base for past context, decisions, or facts. Case-insensitive substring match across all item values. Use before starting complex work to check for relevant prior context.',
+    inputSchema: {
+      type: 'object',
+      properties: {
+        query: { type: 'string', description: 'Search query' },
+        limit: { type: 'number', description: 'Maximum results (default: 10)' },
+      },
+      required: ['query'],
+    },
+  },
+  {
+    name: 'kanecta_recent',
+    description: 'List the most recent captures from the knowledge base.',
+    inputSchema: {
+      type: 'object',
+      properties: {
+        n: { type: 'number', description: 'Number of items to return (default: 10)' },
+      },
+    },
+  },
+  {
+    name: 'kanecta_get',
+    description: 'Get a specific item from the knowledge base by UUID.',
+    inputSchema: {
+      type: 'object',
+      properties: {
+        id: { type: 'string', description: 'Item UUID' },
+      },
+      required: ['id'],
+    },
+  },
+  {
+    name: 'kanecta_get_children',
+    description: 'Get the direct children of an item. Omit parentId to list root-level items.',
+    inputSchema: {
+      type: 'object',
+      properties: {
+        parentId: { type: 'string', description: 'Parent UUID — omit for root items' },
+      },
+    },
+  },
+  {
+    name: 'kanecta_get_tree',
+    description: 'Get an item and its subtree expanded to a given depth.',
+    inputSchema: {
+      type: 'object',
+      properties: {
+        id: { type: 'string', description: 'Root item UUID' },
+        depth: { type: 'number', description: 'Depth to expand (default: 3)' },
+      },
+      required: ['id'],
+    },
+  },
+  {
+    name: 'kanecta_add_item',
+    description: 'Add a new item to the knowledge base with explicit placement. Use kanecta_capture for saving insights — this is for structured data entry.',
+    inputSchema: {
+      type: 'object',
+      properties: {
+        value: { type: 'string', description: 'Item value/content' },
+        type: { type: 'string', description: 'Item type (string, text, object, etc.)' },
+        parentId: { type: 'string', description: 'Parent UUID — omit for root' },
+        sortOrder: { type: 'number', description: 'Sort position (auto-assigned if omitted)' },
+      },
+    },
+  },
+  {
+    name: 'kanecta_update_item',
+    description: 'Update an existing item in the knowledge base.',
+    inputSchema: {
+      type: 'object',
+      properties: {
+        id: { type: 'string', description: 'Item UUID' },
+        value: { type: 'string', description: 'New value/content' },
+        type: { type: 'string', description: 'New type' },
+      },
+      required: ['id'],
+    },
+  },
+  {
+    name: 'kanecta_delete_item',
+    description: 'Delete an item from the knowledge base.',
+    inputSchema: {
+      type: 'object',
+      properties: {
+        id: { type: 'string', description: 'Item UUID' },
+        force: { type: 'boolean', description: 'Delete even if other items link to this one' },
+      },
+      required: ['id'],
+    },
+  },
+];
+
+// ─── Handlers ─────────────────────────────────────────────────────────────────
+
+async function handleCapture(args, connector) {
+  const { text, type = 'text' } = args;
+
+  const secrets = detectSecrets(text);
+  if (secrets.length) {
+    return { error: `Capture rejected — possible secret detected (${secrets.join(', ')}). Kanecta never stores secrets.` };
+  }
+
+  const cfg = readConfig();
+  const today = new Date().toISOString().slice(0, 10);
+
+  let dateBucketId;
+  if (cfg?.lastCaptureDate === today && cfg?.lastCaptureDateId) {
+    dateBucketId = cfg.lastCaptureDateId;
+  } else {
+    const bucket = await connector.addItem({
+      value: today,
+      type: 'string',
+      parentId: cfg?.capturesRootId || null,
+      owner: cfg?.owner || 'kanecta',
+    });
+    dateBucketId = bucket.id;
+    if (cfg) {
+      cfg.lastCaptureDate = today;
+      cfg.lastCaptureDateId = bucket.id;
+      writeConfig(cfg);
+    }
+  }
+
+  const item = await connector.addItem({
+    value: text,
+    type,
+    parentId: dateBucketId,
+    owner: cfg?.owner || 'kanecta',
+  });
+
+  return { id: item.id, date: today, preview: text.slice(0, 120) };
+}
+
+async function handleSearch(args, datastorePath) {
+  const { query, limit = 10 } = args;
+  const q = query.toLowerCase();
+  const all = await walkDataDir(datastorePath);
+  const results = all
+    .filter(i => i.value && typeof i.value === 'string' && i.value.toLowerCase().includes(q))
+    .sort((a, b) => (b.sortOrder || 0) - (a.sortOrder || 0))
+    .slice(0, limit)
+    .map(i => ({ id: i.id, type: i.type, parentId: i.parentId, value: i.value }));
+  return { query, count: results.length, results };
+}
+
+async function handleRecent(args, datastorePath) {
+  const { n = 10 } = args;
+  const all = await walkDataDir(datastorePath);
+
+  // Captures live under date bucket items (value = YYYY-MM-DD)
+  const datePattern = /^\d{4}-\d{2}-\d{2}$/;
+  const dateBuckets = new Map(
+    all.filter(i => typeof i.value === 'string' && datePattern.test(i.value)).map(i => [i.id, i.value])
+  );
+
+  const captures = all
+    .filter(i => i.parentId && dateBuckets.has(i.parentId))
+    .map(i => ({ ...i, _date: dateBuckets.get(i.parentId) }))
+    .sort((a, b) => {
+      if (b._date !== a._date) return b._date.localeCompare(a._date);
+      return (b.sortOrder || 0) - (a.sortOrder || 0);
+    })
+    .slice(0, n)
+    .map(({ _date, ...i }) => ({ id: i.id, type: i.type, date: _date, value: i.value }));
+
+  return { count: captures.length, items: captures };
+}
+
+// ─── MCP protocol ─────────────────────────────────────────────────────────────
+
+function send(msg) {
+  process.stdout.write(JSON.stringify(msg) + '\n');
+}
+
+function sendResult(id, result) {
+  send({ jsonrpc: '2.0', id, result });
+}
+
+function sendError(id, code, message) {
+  send({ jsonrpc: '2.0', id, error: { code, message } });
+}
+
+async function dispatch(name, args, connector, datastorePath) {
+  switch (name) {
+    case 'kanecta_capture':      return handleCapture(args, connector);
+    case 'kanecta_search':       return handleSearch(args, datastorePath);
+    case 'kanecta_recent':       return handleRecent(args, datastorePath);
+    case 'kanecta_get':          return connector.getItem(args.id);
+    case 'kanecta_get_children': return connector.getChildren(args.parentId ?? null);
+    case 'kanecta_get_tree':     return connector.getTree(args.id, { depth: args.depth ?? 3 });
+    case 'kanecta_add_item':     return connector.addItem(args);
+    case 'kanecta_update_item':  { const { id, ...updates } = args; return connector.updateItem(id, updates); }
+    case 'kanecta_delete_item':  return connector.deleteItem(args.id, { force: args.force ?? false }).then(() => ({ deleted: args.id }));
+    default: {
+      const err = new Error(`Unknown tool: ${name}`);
+      err.code = -32601;
+      throw err;
+    }
+  }
+}
+
+function runMcpServer() {
+  const datastorePath = getDatastorePath();
+  const connector = new KanectaConnector({ datastorePath });
+
+  let buf = '';
+  process.stdin.setEncoding('utf8');
+  process.stdin.on('data', chunk => {
+    buf += chunk;
+    let nl;
+    while ((nl = buf.indexOf('\n')) !== -1) {
+      const line = buf.slice(0, nl).trim();
+      buf = buf.slice(nl + 1);
+      if (!line) continue;
+
+      let msg;
+      try { msg = JSON.parse(line); } catch {
+        send({ jsonrpc: '2.0', id: null, error: { code: -32700, message: 'Parse error' } });
+        continue;
+      }
+
+      const { id, method, params = {} } = msg;
+
+      if (method === 'initialize') {
+        sendResult(id, {
+          protocolVersion: '2024-11-05',
+          capabilities: { tools: {} },
+          serverInfo: { name: 'kanecta', version: require('../package.json').version },
+        });
+        continue;
+      }
+
+      if (method === 'notifications/initialized') continue;
+
+      if (method === 'tools/list') {
+        sendResult(id, { tools: TOOLS });
+        continue;
+      }
+
+      if (method === 'tools/call') {
+        const { name, arguments: args = {} } = params;
+        dispatch(name, args, connector, datastorePath)
+          .then(result => {
+            const text = result.error
+              ? `Error: ${result.error}`
+              : JSON.stringify(result, null, 2);
+            sendResult(id, { content: [{ type: 'text', text }], isError: !!result.error });
+          })
+          .catch(err => {
+            if (err.code === -32601) {
+              sendError(id, -32601, err.message);
+            } else {
+              sendResult(id, {
+                content: [{ type: 'text', text: `Error: ${err.message}` }],
+                isError: true,
+              });
+            }
+          });
+        continue;
+      }
+
+      sendError(id, -32601, `Method not found: ${method}`);
+    }
+  });
+
+  process.stdin.on('end', () => process.exit(0));
+}
+
+module.exports = { runMcpServer, TOOLS };
+
+if (require.main === module) {
+  runMcpServer();
+}