@intangle/mcp-server 1.0.0

package/README.md

@@ -0,0 +1,112 @@
+# @intangle/mcp-server
+
+Model Context Protocol server for [Intangle](https://intangle.ai) - AI memory that persists across conversations.
+
+## What is Intangle?
+
+Intangle provides persistent memory for AI assistants like Claude. Your conversations, context, and knowledge are stored and instantly accessible across all your AI interactions.
+
+## Installation
+
+```bash
+npm install -g @intangle/mcp-server
+```
+
+## Setup
+
+1. **Get your API key** from [intangle.app](https://intangle.app) after signing up in "Settings" -> "Connect"
+
+2. **Configure Claude Desktop** by adding to your `claude_desktop_config.json`:
+
+```json
+{
+  "mcpServers": {
+    "intangle": {
+      "command": "npx",
+      "args": ["@intangle/mcp-server"],
+      "env": {
+        "MCP_API_KEY": "your-api-key-here",
+        "NEXT_APP_URL": "https://intangle.app"
+      }
+    }
+  }
+}
+```
+
+> **Note**: The config file location varies by OS:
+> - macOS: `~/Library/Application Support/Claude/claude_desktop_config.json`
+> - Windows: `%APPDATA%\Claude\claude_desktop_config.json`
+> - Linux: `~/.config/Claude/claude_desktop_config.json`
+
+3. **Restart Claude Desktop** to load the MCP server
+
+## Usage
+
+Once configured, Claude will automatically have access to your Intangle memory. You can:
+
+- **Store memories**: "Remember that I prefer TypeScript over JavaScript"
+- **Search memories**: "What did we discuss about the authentication system?"
+- **Organize with topics**: Memories are automatically tagged and organized
+- **Access across conversations**: All memories persist between chat sessions
+
+## Available Tools
+
+The MCP server provides these tools to Claude:
+
+- `add_memory` - Store new memories with topics
+- `search_memories` - Search across all your memories
+- `get_recent_memories` - Retrieve recent memories
+- `list_spaces` - View available memory spaces
+- `get_space_info` - Get details about a specific space
+- `get_entities` - Extract entities from memories
+- `delete_memory` - Remove specific memories
+
+## Features
+
+- **Multi-space support**: Organize memories into separate spaces (personal, work, projects)
+- **Intelligent search**: Combines semantic search with text matching
+- **Entity extraction**: Automatically identifies people, places, and concepts
+- **Temporal awareness**: Tracks when events happened vs when they were recorded
+
+## Development
+
+### Local Development
+
+```bash
+# Clone the repository
+git clone https://github.com/intangle/mcp-server
+cd mcp-server
+
+# Install dependencies
+npm install
+
+# Build the TypeScript code
+npm run build
+
+# Run in development mode
+npm run dev
+```
+
+### Environment Variables
+
+- `MCP_API_KEY`: Your Intangle API key
+- `NEXT_APP_URL`: The Intangle API endpoint (default: https://app.intangle.ai)
+
+## Troubleshooting
+
+If Claude can't access your memories:
+
+1. Verify your API key is correct
+2. Check that the MCP server is listed in Claude's tool menu
+3. Ensure you have an active internet connection
+4. Try restarting Claude Desktop
+
+## Support
+
+- Documentation: [intangle.ai/docs](https://intangle.ai/docs)
+- Issues: [github.com/intangle/mcp-server/issues](https://github.com/intangle/mcp-server/issues)
+- Email: support@intangle.ai
+
+## License
+
+MIT

package/biome.json

@@ -0,0 +1,39 @@
+{
+	"$schema": "https://biomejs.dev/schemas/1.9.4/schema.json",
+	"vcs": {
+		"enabled": false,
+		"clientKind": "git",
+		"useIgnoreFile": false
+	},
+	"files": {
+		"ignoreUnknown": false
+	},
+	"formatter": {
+		"enabled": true,
+		"formatWithErrors": false,
+		"indentStyle": "space",
+		"indentWidth": 2,
+		"lineEnding": "lf",
+		"lineWidth": 80,
+		"attributePosition": "auto"
+	},
+	"linter": {
+		"enabled": true,
+		"rules": {
+			"recommended": true
+		}
+	},
+	"javascript": {
+		"formatter": {
+			"jsxQuoteStyle": "double",
+			"quoteProperties": "asNeeded",
+			"trailingCommas": "es5",
+			"semicolons": "asNeeded",
+			"arrowParentheses": "always",
+			"bracketSpacing": true,
+			"bracketSameLine": false,
+			"quoteStyle": "double",
+			"attributePosition": "auto"
+		}
+	}
+}

package/dist/index.js

@@ -0,0 +1,292 @@
+#!/usr/bin/env node
+/**
+ * Endure MCP Server - Exposes Endure memory functionality through MCP
+ */
+import { config } from "dotenv";
+import fetch from "node-fetch";
+import { Server } from "@modelcontextprotocol/sdk/server/index.js";
+import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
+import { CallToolRequestSchema, ErrorCode, ListToolsRequestSchema, McpError, } from "@modelcontextprotocol/sdk/types.js";
+// Load environment variables from .env and .env.local
+config({ quiet: true });
+config({ path: ".env.local", quiet: true });
+// Base URL for API calls to Next.js app
+const API_BASE_URL = process.env.NEXT_APP_URL || "https://intangle.app";
+const MCP_API_KEY = process.env.MCP_API_KEY;
+// No space configuration needed - AI discovers spaces dynamically
+if (!MCP_API_KEY) {
+    console.error("Error: MCP_API_KEY environment variable is required");
+    console.error("Please set your Intangle API key in the Claude Desktop configuration");
+    process.exit(1);
+}
+console.log("Intangle MCP Server starting - connecting to", API_BASE_URL);
+async function makeApiCall(endpoint, data) {
+    const response = await fetch(`${API_BASE_URL}/api/mcp/${endpoint}`, {
+        method: "POST",
+        headers: {
+            "Content-Type": "application/json",
+            Authorization: `Bearer ${MCP_API_KEY}`,
+        },
+        body: JSON.stringify(data),
+    });
+    if (!response.ok) {
+        throw new Error(`API call failed: ${response.status} ${response.statusText}`);
+    }
+    return response.json();
+}
+const server = new Server({
+    name: "intangle-memory",
+    version: "1.0.0",
+}, {
+    capabilities: {
+        tools: {},
+    },
+});
+const TOOLS = [
+    {
+        name: "add_memory",
+        description: "Store information in the user's memory graph with flexible topics. REQUIRES space_id parameter.",
+        inputSchema: {
+            type: "object",
+            properties: {
+                space_id: {
+                    type: "string",
+                    description: "REQUIRED: Space to store memory in (use list_spaces to see available options)",
+                },
+                title: {
+                    type: "string",
+                    description: "Title/summary of the memory",
+                },
+                content: {
+                    type: "string",
+                    description: "Detailed content of the memory",
+                },
+                topics: {
+                    type: "array",
+                    items: { type: "string" },
+                    description: "Flexible topics/tags for organization (e.g., ['coding', 'react'])",
+                },
+            },
+            required: ["space_id", "title", "content"],
+        },
+    },
+    {
+        name: "search_memories",
+        description: "Search through stored memories using advanced hybrid search (semantic + text + entity relationships). ALWAYS provide either space_id OR space_ids parameter - this is mandatory for all searches.",
+        inputSchema: {
+            type: "object",
+            properties: {
+                space_id: {
+                    type: "string",
+                    description: "REQUIRED (or use space_ids): Space to search in (use list_spaces to see available options)",
+                },
+                space_ids: {
+                    type: "array",
+                    items: { type: "string" },
+                    description: "REQUIRED (or use space_id): Multiple spaces to search across",
+                },
+                query: {
+                    type: "string",
+                    description: "Search query for finding relevant memories",
+                },
+                topics: {
+                    type: "array",
+                    items: { type: "string" },
+                    description: "Filter by specific topics",
+                },
+                max_results: {
+                    type: "number",
+                    description: "Maximum number of results to return",
+                    default: 10,
+                },
+            },
+            required: ["query"],
+        },
+    },
+    {
+        name: "get_recent_memories",
+        description: "Get the most recent memories stored in the system. REQUIRES space_id parameter.",
+        inputSchema: {
+            type: "object",
+            properties: {
+                space_id: {
+                    type: "string",
+                    description: "REQUIRED: Space to get memories from (use list_spaces to see available options)",
+                },
+                topics: {
+                    type: "array",
+                    items: { type: "string" },
+                    description: "Filter by specific topics",
+                },
+                limit: {
+                    type: "number",
+                    description: "Number of recent memories to retrieve",
+                    default: 20,
+                },
+            },
+            required: ["space_id"],
+        },
+    },
+    {
+        name: "get_entities",
+        description: "Get extracted entities (people, places, concepts) from memories",
+        inputSchema: {
+            type: "object",
+            properties: {
+                memory_id: {
+                    type: "string",
+                    description: "Optional memory ID to get entities for specific memory",
+                },
+            },
+        },
+    },
+    {
+        name: "delete_memory",
+        description: "Delete a specific memory item",
+        inputSchema: {
+            type: "object",
+            properties: {
+                memory_id: {
+                    type: "string",
+                    description: "ID of the memory to delete",
+                },
+            },
+            required: ["memory_id"],
+        },
+    },
+    {
+        name: "debug_memory_structure",
+        description: "Debug tool to inspect the current memory structure in the database",
+        inputSchema: {
+            type: "object",
+            properties: {},
+        },
+    },
+    {
+        name: "list_spaces",
+        description: "Get all available spaces with their descriptions and memory counts",
+        inputSchema: {
+            type: "object",
+            properties: {},
+        },
+    },
+    {
+        name: "get_space_info",
+        description: "Get detailed information about a specific space",
+        inputSchema: {
+            type: "object",
+            properties: {
+                space_id: {
+                    type: "string",
+                    description: "ID of space to get info for",
+                },
+            },
+            required: ["space_id"],
+        },
+    },
+];
+server.setRequestHandler(ListToolsRequestSchema, async () => ({
+    tools: TOOLS,
+}));
+async function handleAddMemory(args) {
+    // Require space_id to be provided
+    if (!args.space_id) {
+        throw new Error("space_id is required. Use list_spaces to see available options.");
+    }
+    const memoryData = {
+        topics: [],
+        ...args,
+    };
+    return makeApiCall("add-memory", memoryData);
+}
+async function handleSearchMemories(args) {
+    const { space_id, space_ids, query, topics, max_results = 10, } = args;
+    // Require either space_id or space_ids
+    if (!space_id && (!space_ids || space_ids.length === 0)) {
+        throw new Error("Either space_id or space_ids is required. Use list_spaces to see available options.");
+    }
+    return makeApiCall("search-memories", {
+        space_id,
+        space_ids,
+        query,
+        topics,
+        max_results,
+    });
+}
+async function handleGetRecentMemories(args) {
+    const { space_id, topics, limit = 20, } = args;
+    // Require space_id to be provided
+    if (!space_id) {
+        throw new Error("space_id is required. Use list_spaces to see available options.");
+    }
+    return makeApiCall("get-recent-memories", {
+        space_id,
+        topics,
+        limit,
+    });
+}
+async function handleGetEntities(args) {
+    const { memory_id } = args;
+    return makeApiCall("get-entities", { memory_id });
+}
+async function handleDeleteMemory(args) {
+    const { memory_id } = args;
+    return makeApiCall("delete-memory", { memory_id });
+}
+async function handleDebugStructure() {
+    return makeApiCall("debug-structure", {});
+}
+async function handleListSpaces() {
+    return makeApiCall("list-spaces", {});
+}
+async function handleGetSpaceInfo(args) {
+    const { space_id } = args;
+    return makeApiCall("get-space-info", { space_id });
+}
+server.setRequestHandler(CallToolRequestSchema, async (request) => {
+    const { name, arguments: args } = request.params;
+    try {
+        let result;
+        switch (name) {
+            case "add_memory":
+                result = await handleAddMemory(args);
+                break;
+            case "search_memories":
+                result = await handleSearchMemories(args);
+                break;
+            case "get_recent_memories":
+                result = await handleGetRecentMemories(args);
+                break;
+            case "get_entities":
+                result = await handleGetEntities(args);
+                break;
+            case "delete_memory":
+                result = await handleDeleteMemory(args);
+                break;
+            case "debug_memory_structure":
+                result = await handleDebugStructure();
+                break;
+            case "list_spaces":
+                result = await handleListSpaces();
+                break;
+            case "get_space_info":
+                result = await handleGetSpaceInfo(args);
+                break;
+            default:
+                throw new McpError(ErrorCode.MethodNotFound, `Unknown tool: ${name}`);
+        }
+        return {
+            content: [{ type: "text", text: JSON.stringify(result, null, 2) }],
+        };
+    }
+    catch (error) {
+        throw new McpError(ErrorCode.InternalError, `Error executing tool ${name}: ${error instanceof Error ? error.message : String(error)}`);
+    }
+});
+async function main() {
+    const transport = new StdioServerTransport();
+    await server.connect(transport);
+}
+main().catch(() => {
+    process.exit(1);
+});

package/index.ts

@@ -0,0 +1,377 @@
+#!/usr/bin/env node
+
+/**
+ * Endure MCP Server - Exposes Endure memory functionality through MCP
+ */
+
+import { config } from "dotenv";
+import fetch from "node-fetch";
+import { Server } from "@modelcontextprotocol/sdk/server/index.js";
+import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
+import {
+	CallToolRequestSchema,
+	ErrorCode,
+	ListToolsRequestSchema,
+	McpError,
+} from "@modelcontextprotocol/sdk/types.js";
+
+// Load environment variables from .env and .env.local
+config({ quiet: true });
+config({ path: ".env.local", quiet: true });
+
+// Base URL for API calls to Next.js app
+const API_BASE_URL = process.env.NEXT_APP_URL || "https://intangle.app";
+const MCP_API_KEY = process.env.MCP_API_KEY;
+
+// No space configuration needed - AI discovers spaces dynamically
+
+if (!MCP_API_KEY) {
+	console.error("Error: MCP_API_KEY environment variable is required");
+	console.error("Please set your Intangle API key in the Claude Desktop configuration");
+	process.exit(1);
+}
+
+console.log("Intangle MCP Server starting - connecting to", API_BASE_URL);
+
+async function makeApiCall(endpoint: string, data: any) {
+	const response = await fetch(`${API_BASE_URL}/api/mcp/${endpoint}`, {
+		method: "POST",
+		headers: {
+			"Content-Type": "application/json",
+			Authorization: `Bearer ${MCP_API_KEY}`,
+		},
+		body: JSON.stringify(data),
+	});
+
+	if (!response.ok) {
+		throw new Error(
+			`API call failed: ${response.status} ${response.statusText}`,
+		);
+	}
+
+	return response.json();
+}
+
+const server = new Server(
+	{
+		name: "intangle-memory",
+		version: "1.0.0",
+	},
+	{
+		capabilities: {
+			tools: {},
+		},
+	},
+);
+
+const TOOLS = [
+	{
+		name: "add_memory",
+		description:
+			"Store information in the user's memory graph with flexible topics. REQUIRES space_id parameter.",
+		inputSchema: {
+			type: "object",
+			properties: {
+				space_id: {
+					type: "string",
+					description:
+						"REQUIRED: Space to store memory in (use list_spaces to see available options)",
+				},
+				title: {
+					type: "string",
+					description: "Title/summary of the memory",
+				},
+				content: {
+					type: "string",
+					description: "Detailed content of the memory",
+				},
+				topics: {
+					type: "array",
+					items: { type: "string" },
+					description:
+						"Flexible topics/tags for organization (e.g., ['coding', 'react'])",
+				},
+			},
+			required: ["space_id", "title", "content"],
+		},
+	},
+	{
+		name: "search_memories",
+		description:
+			"Search through stored memories using advanced hybrid search (semantic + text + entity relationships). ALWAYS provide either space_id OR space_ids parameter - this is mandatory for all searches.",
+		inputSchema: {
+			type: "object",
+			properties: {
+				space_id: {
+					type: "string",
+					description:
+						"REQUIRED (or use space_ids): Space to search in (use list_spaces to see available options)",
+				},
+				space_ids: {
+					type: "array",
+					items: { type: "string" },
+					description:
+						"REQUIRED (or use space_id): Multiple spaces to search across",
+				},
+				query: {
+					type: "string",
+					description: "Search query for finding relevant memories",
+				},
+				topics: {
+					type: "array",
+					items: { type: "string" },
+					description: "Filter by specific topics",
+				},
+				max_results: {
+					type: "number",
+					description: "Maximum number of results to return",
+					default: 10,
+				},
+			},
+			required: ["query"],
+		},
+	},
+	{
+		name: "get_recent_memories",
+		description:
+			"Get the most recent memories stored in the system. REQUIRES space_id parameter.",
+		inputSchema: {
+			type: "object",
+			properties: {
+				space_id: {
+					type: "string",
+					description:
+						"REQUIRED: Space to get memories from (use list_spaces to see available options)",
+				},
+				topics: {
+					type: "array",
+					items: { type: "string" },
+					description: "Filter by specific topics",
+				},
+				limit: {
+					type: "number",
+					description: "Number of recent memories to retrieve",
+					default: 20,
+				},
+			},
+			required: ["space_id"],
+		},
+	},
+	{
+		name: "get_entities",
+		description:
+			"Get extracted entities (people, places, concepts) from memories",
+		inputSchema: {
+			type: "object",
+			properties: {
+				memory_id: {
+					type: "string",
+					description: "Optional memory ID to get entities for specific memory",
+				},
+			},
+		},
+	},
+	{
+		name: "delete_memory",
+		description: "Delete a specific memory item",
+		inputSchema: {
+			type: "object",
+			properties: {
+				memory_id: {
+					type: "string",
+					description: "ID of the memory to delete",
+				},
+			},
+			required: ["memory_id"],
+		},
+	},
+	{
+		name: "debug_memory_structure",
+		description:
+			"Debug tool to inspect the current memory structure in the database",
+		inputSchema: {
+			type: "object",
+			properties: {},
+		},
+	},
+	{
+		name: "list_spaces",
+		description:
+			"Get all available spaces with their descriptions and memory counts",
+		inputSchema: {
+			type: "object",
+			properties: {},
+		},
+	},
+	{
+		name: "get_space_info",
+		description: "Get detailed information about a specific space",
+		inputSchema: {
+			type: "object",
+			properties: {
+				space_id: {
+					type: "string",
+					description: "ID of space to get info for",
+				},
+			},
+			required: ["space_id"],
+		},
+	},
+];
+
+server.setRequestHandler(ListToolsRequestSchema, async () => ({
+	tools: TOOLS,
+}));
+
+async function handleAddMemory(args: any) {
+	// Require space_id to be provided
+	if (!args.space_id) {
+		throw new Error(
+			"space_id is required. Use list_spaces to see available options.",
+		);
+	}
+
+	const memoryData = {
+		topics: [],
+		...args,
+	};
+	return makeApiCall("add-memory", memoryData);
+}
+
+async function handleSearchMemories(args: any) {
+	const {
+		space_id,
+		space_ids,
+		query,
+		topics,
+		max_results = 10,
+	} = args as {
+		space_id?: string;
+		space_ids?: string[];
+		query: string;
+		topics?: string[];
+		max_results?: number;
+	};
+
+	// Require either space_id or space_ids
+	if (!space_id && (!space_ids || space_ids.length === 0)) {
+		throw new Error(
+			"Either space_id or space_ids is required. Use list_spaces to see available options.",
+		);
+	}
+
+	return makeApiCall("search-memories", {
+		space_id,
+		space_ids,
+		query,
+		topics,
+		max_results,
+	});
+}
+
+async function handleGetRecentMemories(args: any) {
+	const {
+		space_id,
+		topics,
+		limit = 20,
+	} = args as {
+		space_id?: string;
+		topics?: string[];
+		limit?: number;
+	};
+
+	// Require space_id to be provided
+	if (!space_id) {
+		throw new Error(
+			"space_id is required. Use list_spaces to see available options.",
+		);
+	}
+
+	return makeApiCall("get-recent-memories", {
+		space_id,
+		topics,
+		limit,
+	});
+}
+
+async function handleGetEntities(args: any) {
+	const { memory_id } = args as { memory_id?: string };
+
+	return makeApiCall("get-entities", { memory_id });
+}
+
+async function handleDeleteMemory(args: any) {
+	const { memory_id } = args as {
+		memory_id: string;
+	};
+
+	return makeApiCall("delete-memory", { memory_id });
+}
+
+async function handleDebugStructure() {
+	return makeApiCall("debug-structure", {});
+}
+
+async function handleListSpaces() {
+	return makeApiCall("list-spaces", {});
+}
+
+async function handleGetSpaceInfo(args: any) {
+	const { space_id } = args as { space_id: string };
+	return makeApiCall("get-space-info", { space_id });
+}
+
+server.setRequestHandler(CallToolRequestSchema, async (request: any) => {
+	const { name, arguments: args } = request.params;
+
+	try {
+		let result: any;
+
+		switch (name) {
+			case "add_memory":
+				result = await handleAddMemory(args);
+				break;
+			case "search_memories":
+				result = await handleSearchMemories(args);
+				break;
+			case "get_recent_memories":
+				result = await handleGetRecentMemories(args);
+				break;
+			case "get_entities":
+				result = await handleGetEntities(args);
+				break;
+			case "delete_memory":
+				result = await handleDeleteMemory(args);
+				break;
+			case "debug_memory_structure":
+				result = await handleDebugStructure();
+				break;
+			case "list_spaces":
+				result = await handleListSpaces();
+				break;
+			case "get_space_info":
+				result = await handleGetSpaceInfo(args);
+				break;
+			default:
+				throw new McpError(ErrorCode.MethodNotFound, `Unknown tool: ${name}`);
+		}
+
+		return {
+			content: [{ type: "text", text: JSON.stringify(result, null, 2) }],
+		};
+	} catch (error) {
+		throw new McpError(
+			ErrorCode.InternalError,
+			`Error executing tool ${name}: ${error instanceof Error ? error.message : String(error)}`,
+		);
+	}
+});
+
+async function main() {
+	const transport = new StdioServerTransport();
+	await server.connect(transport);
+}
+
+main().catch(() => {
+	process.exit(1);
+});

package/package.json

@@ -0,0 +1,52 @@
+{
+	"name": "@intangle/mcp-server",
+	"version": "1.0.0",
+	"description": "Model Context Protocol server for Intangle - AI memory that persists across conversations",
+	"main": "dist/index.js",
+	"type": "module",
+	"scripts": {
+		"start": "node dist/index.js",
+		"dev": "tsx watch index.ts",
+		"build": "tsc",
+		"lint": "biome check .",
+		"lint:fix": "biome check --fix .",
+		"prepublishOnly": "npm run build"
+	},
+	"bin": {
+		"intangle-mcp": "./dist/index.js"
+	},
+	"keywords": [
+		"mcp",
+		"model-context-protocol",
+		"claude",
+		"claude-code",
+		"ai",
+		"memory",
+		"knowledge-management",
+		"intangle",
+		"claude-desktop",
+		"anthropic"
+	],
+	"author": "Intangle",
+	"license": "MIT",
+	"repository": {
+		"type": "git",
+		"url": "https://github.com/intangle/mcp-server"
+	},
+	"homepage": "https://intangle.app",
+	"engines": {
+		"node": ">=18.0.0"
+	},
+	"dependencies": {
+		"@modelcontextprotocol/sdk": "^1.0.0",
+		"dotenv": "^17.2.0",
+		"node-fetch": "^3.3.2"
+	},
+	"devDependencies": {
+		"@biomejs/biome": "^1.9.4",
+		"@types/node": "^22.0.0",
+		"@types/node-fetch": "^2.6.12",
+		"tsx": "^4.0.0",
+		"typescript": "^5.0.0"
+	}
+}

package/tsconfig.json

@@ -0,0 +1,18 @@
+{
+  "compilerOptions": {
+    "target": "ES2022",
+    "module": "ESNext",
+    "moduleResolution": "node",
+    "outDir": "./dist",
+    "rootDir": "./",
+    "strict": true,
+    "skipLibCheck": true,
+    "esModuleInterop": true,
+    "allowSyntheticDefaultImports": true,
+    "forceConsistentCasingInFileNames": true,
+    "resolveJsonModule": true,
+    "isolatedModules": true
+  },
+  "include": ["**/*.ts"],
+  "exclude": ["node_modules", "dist"]
+}