taru-mcp 0.1.4 → 0.1.6

package/.claude/hooks/post-stop.sh

@@ -0,0 +1,32 @@
+#!/bin/bash
+# Stop hook: If WebSearch was used but store_document was not, block and remind.
+
+INPUT=$(cat)
+TRANSCRIPT=$(echo "$INPUT" | jq -r '.transcript_path')
+
+if [ -z "$TRANSCRIPT" ] || [ ! -f "$TRANSCRIPT" ]; then
+  exit 0
+fi
+
+# Check if any web search/fetch was done
+HAS_WEB=$(grep -c '"WebSearch"\|"WebFetch"' "$TRANSCRIPT" 2>/dev/null || echo "0")
+
+if [ "$HAS_WEB" -eq 0 ]; then
+  exit 0
+fi
+
+# Check if store_document was called
+HAS_STORE=$(grep -c 'store_document' "$TRANSCRIPT" 2>/dev/null || echo "0")
+
+if [ "$HAS_STORE" -gt 0 ]; then
+  exit 0
+fi
+
+# Web search was done but nothing stored
+cat <<'EOF'
+{
+  "decision": "block",
+  "reason": "You performed web searches but did not store the findings. Use store_document to save the key information you found to the taru knowledge graph before finishing."
+}
+EOF
+exit 0

package/.claude/hooks/pre-websearch.sh

@@ -0,0 +1,25 @@
+#!/bin/bash
+# PreToolUse hook: Before WebSearch, check if search_graph was already called.
+# If not, block and tell Claude to search taru first.
+
+INPUT=$(cat)
+TRANSCRIPT=$(echo "$INPUT" | jq -r '.transcript_path')
+
+if [ -z "$TRANSCRIPT" ] || [ ! -f "$TRANSCRIPT" ]; then
+  exit 0
+fi
+
+# Check if search_graph was already called in this conversation
+if grep -q 'store_document\|search_graph' "$TRANSCRIPT" 2>/dev/null; then
+  # Already searched taru, allow web search
+  exit 0
+fi
+
+# Block: tell Claude to search taru first
+cat <<'EOF'
+{
+  "decision": "block",
+  "reason": "Search the taru knowledge graph first (search_graph) before using web search. The answer might already be stored."
+}
+EOF
+exit 0

package/README.md

@@ -6,18 +6,86 @@ Zero dependencies. Pure Node.js. Works with any MCP client.
 
 ## Quick Setup
 
+### macOS / Linux
+
 ```bash
 curl -fsSL https://raw.githubusercontent.com/arupa-inc/taru-mcp/main/setup.sh | bash
 ```
 
+### Windows (PowerShell)
+
+```powershell
+irm https://raw.githubusercontent.com/arupa-inc/taru-mcp/main/setup.ps1 | iex
+```
+
 The script will ask you:
 1. **Project folder name** — creates the workspace directory
 2. **AI client** — Claude Code, Codex, or both
-3. **API token** — optional, can add later
+3. **Workspace token** — taru workspace token (`xxv_...`). Can be entered later if you don't have it yet.
 
 It handles `npm init`, `taru-mcp` installation, agent file (`CLAUDE.md` / `AGENTS.md`) setup, and MCP registration automatically.
 
-Get your API token from the taru web console: **Settings > API Key**.
+Get your workspace token from the taru web console: **Settings > API Key**.
+
+## Manual Setup
+
+If the setup script doesn't work, follow these steps:
+
+### 1. Install
+
+```bash
+mkdir my-project && cd my-project
+npm init -y
+npm install taru-mcp
+```
+
+### 2. Copy agent instructions
+
+```bash
+# For Claude Code
+cp node_modules/taru-mcp/samples/CLAUDE.md ./CLAUDE.md
+
+# For Codex
+cp node_modules/taru-mcp/samples/AGENTS.md ./AGENTS.md
+```
+
+### 3. Register MCP server
+
+```bash
+# Claude Code
+claude mcp add taru -- npx taru-mcp --url https://taru-api.arupa.io --token xxv_your_token
+
+# Codex
+codex mcp add taru -- npx taru-mcp --url https://taru-api.arupa.io --token xxv_your_token
+```
+
+### 4. Or configure MCP manually
+
+If `claude mcp add` doesn't work, create `.mcp.json` in your project root:
+
+```json
+{
+  "mcpServers": {
+    "taru": {
+      "command": "npx",
+      "args": ["taru-mcp", "--url", "https://taru-api.arupa.io", "--token", "xxv_your_token"]
+    }
+  }
+}
+```
+
+For Claude Code global config (`~/.claude.json`):
+
+```json
+{
+  "mcpServers": {
+    "taru": {
+      "command": "npx",
+      "args": ["taru-mcp", "--url", "https://taru-api.arupa.io", "--token", "xxv_your_token"]
+    }
+  }
+}
+```
 
 ## Tools
 
@@ -30,8 +98,6 @@ Once connected, these MCP tools are available to the AI:
 | `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

package/bin/taru-mcp.mjs

@@ -39,7 +39,9 @@ Examples:
 }
 
 url = url.replace(/\/+$/, "");
-const endpoint = `${url}/mcp/${workspaceId}`;
+// If workspace ID was explicitly provided, use the scoped endpoint; otherwise use token-based auto endpoint
+const hasExplicitWorkspace = args.some(a => a === "--workspace-id" || a === "-w") || env.TARU_WORKSPACE_ID;
+const endpoint = hasExplicitWorkspace ? `${url}/mcp/${workspaceId}` : `${url}/mcp`;
 const isHttps = endpoint.startsWith("https://");
 
 stderr.write(`[taru-mcp] endpoint: ${endpoint}\n`);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "taru-mcp",
-  "version": "0.1.4",
+  "version": "0.1.6",
   "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"
@@ -9,7 +9,9 @@
   "files": [
     "bin/",
     "samples/",
+    ".claude/",
     "setup.sh",
+    "setup.ps1",
     "README.md"
   ],
   "keywords": [

package/samples/AGENTS.md

@@ -9,8 +9,6 @@ You have access to the taru MCP server — a research knowledge graph with tempo
 - 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
@@ -39,11 +37,14 @@ You have access to the taru MCP server — a research knowledge graph with tempo
 
 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.
+8. **Proactive knowledge capture — ALWAYS store what you learn:**
+   - When you find useful information (web search, file reading, research), store it via store_document immediately. Do NOT wait to be asked.
+   - When a user expresses an opinion, makes a decision, or shares an insight, store it as doc_type="opinion".
+   - When you find factual information from web searches or documents, store it as doc_type="document".
+   - Include the full context (conversation, URL content, file content) in the content field.
+   - Use source_file="web://url" for web findings, "conversation://session" for conversational insights, "file://path" for local files.
+   - Extract the core insight as core_claim, even if it was found casually.
+   - Always provide a reason explaining why this knowledge is worth storing.
 
 9. **Search result interpretation:**
    - disputed_by present → present both perspectives

package/samples/CLAUDE.md

@@ -9,8 +9,6 @@ You have access to the taru MCP server — a research knowledge graph with tempo
 - 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
@@ -39,11 +37,14 @@ You have access to the taru MCP server — a research knowledge graph with tempo
 
 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.
+8. **Proactive knowledge capture — ALWAYS store what you learn:**
+   - When you find useful information (web search, file reading, research), store it via store_document immediately. Do NOT wait to be asked.
+   - When a user expresses an opinion, makes a decision, or shares an insight, store it as doc_type="opinion".
+   - When you find factual information from web searches or documents, store it as doc_type="document".
+   - Include the full context (conversation, URL content, file content) in the content field.
+   - Use source_file="web://url" for web findings, "conversation://session" for conversational insights, "file://path" for local files.
+   - Extract the core insight as core_claim, even if it was found casually.
+   - Always provide a reason explaining why this knowledge is worth storing.
 
 9. **Search result interpretation:**
    - disputed_by present → present both perspectives

package/setup.ps1

@@ -0,0 +1,116 @@
+# taru MCP setup script for Windows
+# Usage:
+#   irm https://raw.githubusercontent.com/arupa-inc/taru-mcp/main/setup.ps1 | iex
+
+$ErrorActionPreference = "Stop"
+$URL = "https://taru-api.arupa.io"
+
+Write-Host ""
+Write-Host "  🌳 taru MCP Setup" -ForegroundColor Green
+Write-Host ""
+
+# 1. Ask project folder name
+$Folder = Read-Host "Project folder name"
+if (-not $Folder) {
+    Write-Host "Error: folder name is required" -ForegroundColor Red
+    exit 1
+}
+
+if (Test-Path $Folder) {
+    Write-Host "==> Directory '$Folder' already exists, using it."
+} else {
+    New-Item -ItemType Directory -Path $Folder | Out-Null
+    Write-Host "==> Created '$Folder'"
+}
+Set-Location $Folder
+
+# 2. Ask client type
+Write-Host ""
+Write-Host "Which AI client do you use?"
+Write-Host "  1) Claude Code"
+Write-Host "  2) Codex"
+Write-Host "  3) Not sure (copies both CLAUDE.md and AGENTS.md)"
+Write-Host ""
+$ClientChoice = Read-Host "Choose [1/2/3]"
+
+switch ($ClientChoice) {
+    "1" { $Client = "claude" }
+    "2" { $Client = "codex" }
+    default { $Client = "both" }
+}
+
+# 3. Ask token (skippable)
+Write-Host ""
+$Token = Read-Host "Workspace token (xxv_..., press Enter to add later)"
+
+# Check npm
+if (-not (Get-Command npm -ErrorAction SilentlyContinue)) {
+    Write-Host "Error: 'npm' not found. Install Node.js first." -ForegroundColor Red
+    exit 1
+}
+
+# Init & install
+if (-not (Test-Path "package.json")) {
+    Write-Host "==> Initializing package.json..."
+    npm init -y --silent 2>&1 | Out-Null
+}
+
+Write-Host "==> Installing taru-mcp..."
+npm install taru-mcp --silent
+
+# Copy agent files
+function Copy-AgentFile($File) {
+    $src = "node_modules/taru-mcp/samples/$File"
+    if (Test-Path $File) {
+        Write-Host "==> $File already exists, appending taru instructions..."
+        Add-Content -Path $File -Value ""
+        Get-Content $src | Add-Content -Path $File
+    } else {
+        Copy-Item $src -Destination "./$File"
+        Write-Host "==> Created $File"
+    }
+}
+
+if ($Client -eq "claude") {
+    Copy-AgentFile "CLAUDE.md"
+} elseif ($Client -eq "codex") {
+    Copy-AgentFile "AGENTS.md"
+} else {
+    Copy-AgentFile "CLAUDE.md"
+    Copy-AgentFile "AGENTS.md"
+}
+
+# Register MCP server
+function Register-MCP($Cli) {
+    $tokenArgs = ""
+    if ($Token) { $tokenArgs = " --token $Token" }
+
+    if (Get-Command $Cli -ErrorAction SilentlyContinue) {
+        Write-Host "==> Registering MCP server with $Cli..."
+        $cmd = "$Cli mcp add taru -- npx taru-mcp --url $URL$tokenArgs"
+        Invoke-Expression $cmd
+    } else {
+        Write-Host "==> '$Cli' not found, skipping MCP registration."
+        Write-Host "    Run this later: $Cli mcp add taru -- npx taru-mcp --url $URL$tokenArgs"
+    }
+}
+
+if ($Client -eq "claude") {
+    Register-MCP "claude"
+} elseif ($Client -eq "codex") {
+    Register-MCP "codex"
+} else {
+    Register-MCP "claude"
+    Register-MCP "codex"
+}
+
+Write-Host ""
+Write-Host "  ✅ Setup complete!" -ForegroundColor Green
+Write-Host ""
+Write-Host "  Project: $(Get-Location)"
+if ($Client -eq "claude" -or $Client -eq "both") { Write-Host "  Agent file: ./CLAUDE.md" }
+if ($Client -eq "codex" -or $Client -eq "both") { Write-Host "  Agent file: ./AGENTS.md" }
+if ($Token) { Write-Host "  Token: configured" } else { Write-Host "  Token: not set yet (add via settings)" }
+Write-Host ""
+Write-Host "  Open this folder in your AI client to start growing the tree."
+Write-Host ""

package/setup.sh

@@ -12,7 +12,7 @@ echo "  🌳 taru MCP Setup"
 echo ""
 
 # 1. Ask project folder name
-read -rp "Project folder name: " FOLDER
+read -rp "Project folder name: " FOLDER </dev/tty
 if [ -z "$FOLDER" ]; then
   echo "Error: folder name is required"
   exit 1
@@ -33,7 +33,7 @@ echo "  1) Claude Code"
 echo "  2) Codex"
 echo "  3) Not sure (copies both CLAUDE.md and AGENTS.md)"
 echo ""
-read -rp "Choose [1/2/3]: " CLIENT_CHOICE
+read -rp "Choose [1/2/3]: " CLIENT_CHOICE </dev/tty
 
 case "$CLIENT_CHOICE" in
   1) CLIENT="claude" ;;
@@ -43,7 +43,7 @@ esac
 
 # 3. Ask token (skippable)
 echo ""
-read -rp "API token (press Enter to skip): " TOKEN
+read -rp "Workspace token (xxv_..., press Enter to add later): " TOKEN </dev/tty
 
 # Check npm
 if ! command -v npm &>/dev/null; then
@@ -108,13 +108,53 @@ else
   register_mcp "codex"
 fi
 
+# Install Claude Code hooks (search taru first, store after web search)
+if [ "$CLIENT" = "claude" ] || [ "$CLIENT" = "both" ]; then
+  if [ -d "node_modules/taru-mcp/.claude/hooks" ]; then
+    mkdir -p .claude/hooks
+    cp node_modules/taru-mcp/.claude/hooks/*.sh .claude/hooks/
+    chmod +x .claude/hooks/*.sh
+
+    # Write hooks config to .claude/settings.json
+    mkdir -p .claude
+    cat > .claude/settings.json <<'HOOKS'
+{
+  "hooks": {
+    "PreToolUse": [
+      {
+        "matcher": "WebSearch",
+        "hooks": [
+          {
+            "type": "command",
+            "command": ".claude/hooks/pre-websearch.sh"
+          }
+        ]
+      }
+    ],
+    "Stop": [
+      {
+        "hooks": [
+          {
+            "type": "command",
+            "command": ".claude/hooks/post-stop.sh"
+          }
+        ]
+      }
+    ]
+  }
+}
+HOOKS
+    echo "==> Installed taru hooks (search-first + store-after-search)"
+  fi
+fi
+
 echo ""
 echo "  ✅ Setup complete!"
 echo ""
 echo "  Project: $(pwd)"
 [ "$CLIENT" = "claude" ] || [ "$CLIENT" = "both" ] && echo "  Agent file: ./CLAUDE.md"
 [ "$CLIENT" = "codex" ] || [ "$CLIENT" = "both" ] && echo "  Agent file: ./AGENTS.md"
-[ -n "$TOKEN" ] && echo "  Token: configured" || echo "  Token: skipped (add later via settings)"
+[ -n "$TOKEN" ] && echo "  Token: configured" || echo "  Token: not set yet (add via settings)"
 echo ""
 echo "  Open this folder in your AI client to start growing the tree."
 echo ""