taru-mcp 0.1.0

package/README.md

@@ -0,0 +1,81 @@
+# taru-mcp
+
+MCP server for [taru](https://taru.arupa.io) — connect Claude Code or Codex to your team's shared knowledge graph.
+
+Zero dependencies. Pure Node.js. Works with any MCP client.
+
+## Install
+
+### Claude Code
+
+```bash
+claude mcp add taru -- npx -y taru-mcp \
+  --url https://your-server.com \
+  --token xxv_your_token
+
+# Copy the agent instructions to your project
+cp node_modules/taru-mcp/samples/CLAUDE.md ./CLAUDE.md
+```
+
+### Codex (OpenAI)
+
+```bash
+codex mcp add taru -- npx -y taru-mcp \
+  --url https://your-server.com \
+  --token xxv_your_token
+
+# Copy the agent instructions to your project
+cp node_modules/taru-mcp/samples/AGENTS.md ./AGENTS.md
+```
+
+### Agent instructions
+
+The `samples/` directory contains ready-to-use instruction files:
+
+| File | For | Description |
+|------|-----|-------------|
+| `samples/CLAUDE.md` | Claude Code | Drop into your project root |
+| `samples/AGENTS.md` | Codex | Drop into your project root |
+
+These files teach the AI how to use taru tools, classify documents vs opinions, handle conflicts, and set confidence scores. **Copy the appropriate file to your project root** after installing.
+
+## Options
+
+| Flag | Env | Default | Description |
+|------|-----|---------|-------------|
+| `--url`, `-u` | `TARU_URL` | `http://localhost:9120` | Taru server URL |
+| `--workspace-id`, `-w` | `TARU_WORKSPACE_ID` | `00000000-...0001` | Workspace UUID |
+| `--token`, `-t` | `TARU_API_TOKEN` | — | API token (`xxv_...`) |
+
+Get your API token from the taru web console: **Workspaces → Members → API Key**.
+
+## Tools
+
+Once connected, these MCP tools are available to the AI:
+
+| Tool | Description |
+|------|-------------|
+| `search_graph` | Search the knowledge base by natural language query |
+| `read_full_document` | Read full document content by UUID |
+| `store_document` | Store a document or opinion with auto-conflict detection |
+| `list_documents` | List all documents in the workspace |
+| `list_conflicts` | View pending knowledge conflicts |
+| `web_search` | Search the web via DuckDuckGo |
+| `web_fetch` | Fetch and extract text from a URL |
+| `rebalance` | Merge similar keywords, clean up orphan nodes |
+
+## How it works
+
+`taru-mcp` is a thin proxy: it reads JSON-RPC (MCP protocol) from stdin, forwards each request to the taru server over HTTP, and writes the response to stdout. No database, no AI calls — just I/O.
+
+```
+MCP Client (Claude/Codex)
+    ↕ stdin/stdout (JSON-RPC)
+taru-mcp (this package)
+    ↕ HTTP POST
+Taru Server (knowledge graph + embeddings + graph DB)
+```
+
+## License
+
+MIT

package/bin/taru-mcp.mjs

@@ -0,0 +1,114 @@
+#!/usr/bin/env node
+
+import { createInterface } from "node:readline";
+import { argv, env, stderr, stdout } from "node:process";
+import { request as httpsRequest } from "node:https";
+import { request as httpRequest } from "node:http";
+
+// --- Parse args ---
+
+const args = argv.slice(2);
+let url = env.TARU_URL || "http://localhost:9120";
+let workspaceId = env.TARU_WORKSPACE_ID || "00000000-0000-0000-0000-000000000001";
+let token = env.TARU_API_TOKEN || "";
+
+for (let i = 0; i < args.length; i++) {
+  if ((args[i] === "--url" || args[i] === "-u") && args[i + 1]) {
+    url = args[++i];
+  } else if ((args[i] === "--workspace-id" || args[i] === "-w") && args[i + 1]) {
+    workspaceId = args[++i];
+  } else if ((args[i] === "--token" || args[i] === "-t") && args[i + 1]) {
+    token = args[++i];
+  } else if (args[i] === "--help" || args[i] === "-h") {
+    stderr.write(`taru-mcp — MCP proxy for taru knowledge graph
+
+Usage:
+  npx taru-mcp [options]
+
+Options:
+  --url, -u           Taru server URL (env: TARU_URL, default: http://localhost:9120)
+  --workspace-id, -w  Workspace UUID (env: TARU_WORKSPACE_ID)
+  --token, -t         API token (env: TARU_API_TOKEN)
+  --help, -h          Show this help
+
+Examples:
+  claude mcp add taru -- npx -y taru-mcp --url https://taru.example.com --token xxv_...
+  codex mcp add taru -- npx -y taru-mcp -u http://localhost:9120 -w <uuid>
+`);
+    process.exit(0);
+  }
+}
+
+url = url.replace(/\/+$/, "");
+const endpoint = `${url}/mcp/${workspaceId}`;
+const isHttps = endpoint.startsWith("https://");
+
+stderr.write(`[taru-mcp] endpoint: ${endpoint}\n`);
+
+// --- JSON-RPC proxy: stdin → HTTP POST → stdout ---
+
+const rl = createInterface({ input: process.stdin });
+
+rl.on("line", async (line) => {
+  if (!line.trim()) return;
+
+  try {
+    const body = await post(endpoint, line);
+
+    // 202 Accepted = notification, no response needed
+    if (body === null) return;
+
+    stdout.write(body + "\n");
+  } catch (err) {
+    const parsed = safeParse(line);
+    const id = parsed?.id ?? null;
+    const errResp = JSON.stringify({
+      jsonrpc: "2.0",
+      id,
+      error: { code: -32603, message: `server unreachable: ${err.message}` },
+    });
+    stdout.write(errResp + "\n");
+  }
+});
+
+rl.on("close", () => process.exit(0));
+
+// --- HTTP POST helper ---
+
+function post(targetUrl, body) {
+  return new Promise((resolve, reject) => {
+    const parsed = new URL(targetUrl);
+    const requester = isHttps ? httpsRequest : httpRequest;
+
+    const headers = { "Content-Type": "application/json" };
+    if (token) headers["Authorization"] = `Bearer ${token}`;
+
+    const req = requester(
+      parsed,
+      { method: "POST", headers },
+      (res) => {
+        const chunks = [];
+        res.on("data", (chunk) => chunks.push(chunk));
+        res.on("end", () => {
+          if (res.statusCode === 202) {
+            resolve(null);
+            return;
+          }
+          resolve(Buffer.concat(chunks).toString());
+        });
+      }
+    );
+
+    req.on("error", reject);
+    req.write(body);
+    req.end();
+  });
+}
+
+function safeParse(s) {
+  try {
+    return JSON.parse(s);
+  } catch {
+    return null;
+  }
+}

package/package.json

@@ -0,0 +1,30 @@
+{
+  "name": "taru-mcp",
+  "version": "0.1.0",
+  "description": "MCP server for taru knowledge graph — connect Claude Code or Codex to your team's shared brain",
+  "bin": {
+    "taru-mcp": "./bin/taru-mcp.mjs"
+  },
+  "type": "module",
+  "files": [
+    "bin/",
+    "samples/",
+    "README.md"
+  ],
+  "keywords": [
+    "mcp",
+    "knowledge-graph",
+    "taru",
+    "claude",
+    "codex",
+    "model-context-protocol"
+  ],
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/carl/taru-mcp"
+  },
+  "license": "MIT",
+  "engines": {
+    "node": ">=18"
+  }
+}

package/samples/AGENTS.md

@@ -0,0 +1,54 @@
+## taru Knowledge Graph
+
+You have access to the taru MCP server — a research knowledge graph with temporal knowledge management.
+
+### Tools
+
+- search_graph: Search knowledge base by English query
+- read_full_document: Read full document content by UUID
+- store_document: Store extracted knowledge (handles embedding + graph)
+- list_documents: List all documents with status and confidence
+- list_conflicts: View pending knowledge conflicts
+- web_search: Search the web (DuckDuckGo)
+- web_fetch: Fetch text content from a URL
+- rebalance: Clean up the knowledge graph (merge keywords, remove orphans)
+
+### Rules
+
+1. **Always search before storing.** Before store_document, call search_graph with the core claim to check for conflicts.
+
+2. **Document vs Opinion classification:**
+   - doc_type="document": Objective, research-backed facts, data, verified information.
+   - doc_type="opinion": Subjective insights, ideas, hypotheses, preferences, or conversational knowledge from humans.
+   - When a user shares a personal view, idea, preference, or experience → opinion.
+   - When referencing published research, official data, or verified facts → document.
+   - Opinions get lower default confidence (0.50) than documents (0.85).
+   - Store the original conversation/context in content field for traceability.
+
+3. **Conflict resolution:**
+   - supersedes_doc_id: Only when new info definitively invalidates old (retraction, correction). Marks old doc invalid.
+   - disputes_doc_id: Legitimate disagreement (competing theories). Both remain valid. USE THIS FOR COMPETING SCIENTIFIC CLAIMS.
+   - refines_doc_id: New info adds nuance to old. Both remain valid.
+   - Do NOT default to superseding. Competing claims must coexist.
+
+4. **Confidence scores:** 0.95 (meta-analysis) → 0.85 (peer-reviewed, default for documents) → 0.70 (preprint) → 0.50 (opinion, default) → 0.30 (unverified)
+
+5. **Extraction in English.** All titles, core_claims, keywords must be English for embedding consistency. Keywords lowercase and specific.
+
+6. **One claim per document.** Multiple independent claims from one source → separate store_document calls.
+
+7. **Source traceability.** Always set source_file: web://url, file://name, mcp://topic, or conversation://context. Set valid_from to current time for opinions.
+
+8. **Capturing conversational knowledge:**
+   - When a user expresses an opinion or idea during conversation, store it proactively.
+   - Include the full conversational context in the content field.
+   - Use source_file="conversation://session" to mark conversational origins.
+   - Extract the core insight as core_claim, even if the user expressed it casually.
+
+9. **Search result interpretation:**
+   - disputed_by present → present both perspectives
+   - confidence → note reliability level
+   - valid_until set → superseded, prefer newer but note history
+   - doc_type=opinion → present as "team insight" not "established fact"
+
+10. **Maintenance.** Run list_conflicts after bulk ingestion. Run rebalance after storing many documents.

package/samples/CLAUDE.md

@@ -0,0 +1,54 @@
+## taru Knowledge Graph
+
+You have access to the taru MCP server — a research knowledge graph with temporal knowledge management.
+
+### Tools
+
+- search_graph: Search knowledge base by English query
+- read_full_document: Read full document content by UUID
+- store_document: Store extracted knowledge (handles embedding + graph)
+- list_documents: List all documents with status and confidence
+- list_conflicts: View pending knowledge conflicts
+- web_search: Search the web (DuckDuckGo)
+- web_fetch: Fetch text content from a URL
+- rebalance: Clean up the knowledge graph (merge keywords, remove orphans)
+
+### Rules
+
+1. **Always search before storing.** Before store_document, call search_graph with the core claim to check for conflicts.
+
+2. **Document vs Opinion classification:**
+   - doc_type="document": Objective, research-backed facts, data, verified information.
+   - doc_type="opinion": Subjective insights, ideas, hypotheses, preferences, or conversational knowledge from humans.
+   - When a user shares a personal view, idea, preference, or experience → opinion.
+   - When referencing published research, official data, or verified facts → document.
+   - Opinions get lower default confidence (0.50) than documents (0.85).
+   - Store the original conversation/context in content field for traceability.
+
+3. **Conflict resolution:**
+   - supersedes_doc_id: Only when new info definitively invalidates old (retraction, correction). Marks old doc invalid.
+   - disputes_doc_id: Legitimate disagreement (competing theories). Both remain valid. USE THIS FOR COMPETING SCIENTIFIC CLAIMS.
+   - refines_doc_id: New info adds nuance to old. Both remain valid.
+   - Do NOT default to superseding. Competing claims must coexist.
+
+4. **Confidence scores:** 0.95 (meta-analysis) → 0.85 (peer-reviewed, default for documents) → 0.70 (preprint) → 0.50 (opinion, default) → 0.30 (unverified)
+
+5. **Extraction in English.** All titles, core_claims, keywords must be English for embedding consistency. Keywords lowercase and specific.
+
+6. **One claim per document.** Multiple independent claims from one source → separate store_document calls.
+
+7. **Source traceability.** Always set source_file: web://url, file://name, mcp://topic, or conversation://context. Set valid_from to current time for opinions.
+
+8. **Capturing conversational knowledge:**
+   - When a user expresses an opinion or idea during conversation, store it proactively.
+   - Include the full conversational context in the content field.
+   - Use source_file="conversation://session" to mark conversational origins.
+   - Extract the core insight as core_claim, even if the user expressed it casually.
+
+9. **Search result interpretation:**
+   - disputed_by present → present both perspectives
+   - confidence → note reliability level
+   - valid_until set → superseded, prefer newer but note history
+   - doc_type=opinion → present as "team insight" not "established fact"
+
+10. **Maintenance.** Run list_conflicts after bulk ingestion. Run rebalance after storing many documents.