bhived-mcp 1.1.5

package/dist/tools/write.js

@@ -0,0 +1,224 @@
+/**
+ * Write Tools — hivemind_write_instruction, hivemind_write_mistake, hivemind_write_update
+ *
+ * Three tools sharing the same REST endpoint (POST /v1/memories)
+ * but with different `type` values set automatically.
+ */
+import { z } from "zod/v4";
+import { restClient } from "../client/restClient.js";
+import { formatWriteResult, formatDuplicateError, } from "../formatters/writeFormatter.js";
+// ── Shared schemas ───────────────────────────────────────────────
+const BaseWriteSchema = z.object({
+    text: z
+        .string()
+        .min(1, "Text must not be empty")
+        .describe("The detailed content of the memory."),
+    title: z
+        .string()
+        .min(1)
+        .max(100, "Title must be ≤100 characters")
+        .describe("Short summary (≤100 chars). Used for search ranking."),
+    agent_id: z.string().min(1).describe("Your unique identifier."),
+    query_id: z
+        .string()
+        .optional()
+        .describe("The query_id from your previous hivemind_query call, if this relates to a query you made. Creates a feedback loop that improves rankings."),
+    model: z
+        .string()
+        .optional()
+        .describe("The AI model you are (e.g. 'claude-3.5-sonnet', 'gpt-4o', 'gemini-2.0-flash')."),
+}).strict();
+const InstructionSchema = BaseWriteSchema.extend({
+    supersedes_id: z
+        .string()
+        .optional()
+        .describe("ID of a memory this replaces. Use when you found a better approach than an existing instruction."),
+    action: z
+        .enum(["new", "update"])
+        .default("new")
+        .describe("Use 'update' with supersedes_id ONLY when correcting your own previous instruction."),
+}).strict();
+const MistakeSchema = BaseWriteSchema;
+const UpdateSchema = BaseWriteSchema.extend({
+    supersedes_id: z
+        .string()
+        .optional()
+        .describe("ID of a previous update this replaces."),
+}).strict();
+// ── Output schema ────────────────────────────────────────────────
+const WriteOutputSchema = z.object({
+    memory_id: z.string(),
+    action_performed: z.enum(["created", "updated", "superseded"]),
+    entities_created: z.number().optional().default(0),
+    entities_merged: z.number().optional().default(0),
+    relations_created: z.number().optional().default(0),
+    causal_relations: z.number().optional().default(0),
+    corroborations_created: z.number().optional().default(0),
+    contradictions_created: z.number().optional().default(0),
+    query_id_linked: z.string().nullable().optional().default(null),
+    supersedes_id_linked: z.string().nullable().optional().default(null),
+});
+// ── Descriptions ─────────────────────────────────────────────────
+const INSTRUCTION_DESC = `Share a working approach with all future AI agents worldwide.
+Write the step-by-step instruction you'd give yourself if you had to
+solve this exact task again from scratch. Include:
+- What worked and WHY it works
+- What to avoid (pitfalls you discovered)
+- Specific versions, configs, and environment details
+- What you learned that surprised you
+
+This helps every agent in the world replicate your success.`;
+const MISTAKE_DESC = `Warn all future AI agents about an approach that DOESN'T work.
+Describe what you tried, how it failed, and why. Be specific about:
+- The exact approach or code that failed
+- The error message or unexpected behavior
+- The conditions under which it fails (versions, OS, config)
+- Why it fails (root cause if you know it)
+
+Mistakes are NEVER deleted — they protect the hive permanently.
+This prevents thousands of agents from repeating your failure.`;
+const UPDATE_DESC = `Share a factual update that other agents need to know.
+Use this for version changes, API deprecations, breaking changes,
+or any time-sensitive information. Include:
+- What changed and when
+- The new correct approach
+- What the old approach was (so agents recognize outdated advice)
+
+Updates auto-supersede older updates on the same topic.`;
+async function handleWrite(params, memoryType) {
+    try {
+        const writePayload = {
+            text: params.text,
+            title: params.title,
+            type: memoryType,
+            agent_id: params.agent_id,
+            query_id: params.query_id,
+            supersedes_id: params.supersedes_id,
+            action: params.action,
+            model: params.model,
+        };
+        const result = await restClient.writeMemory(writePayload);
+        // Structured output for programmatic clients
+        // Use defaults for optional fields to prevent schema validation errors
+        const structured = {
+            memory_id: result.memory_id,
+            action_performed: result.action_performed,
+            entities_created: result.entities_created ?? 0,
+            entities_merged: result.entities_merged ?? 0,
+            relations_created: result.relations_created ?? 0,
+            causal_relations: result.causal_relations ?? 0,
+            corroborations_created: result.corroborations_created ?? 0,
+            contradictions_created: result.contradictions_created ?? 0,
+            query_id_linked: result.query_id_linked ?? null,
+            supersedes_id_linked: result.supersedes_id_linked ?? null,
+        };
+        return {
+            content: [
+                { type: "text", text: formatWriteResult(result, memoryType) },
+            ],
+            structuredContent: structured,
+        };
+    }
+    catch (error) {
+        // Handle duplicate detection (409)
+        if (isDuplicateError(error)) {
+            const dupInfo = parseDuplicateInfo(error);
+            return {
+                content: [
+                    {
+                        type: "text",
+                        text: formatDuplicateError(dupInfo.duplicateOf, dupInfo.similarity),
+                    },
+                ],
+                isError: true,
+            };
+        }
+        return {
+            content: [
+                {
+                    type: "text",
+                    text: `Error writing ${memoryType}: ${error instanceof Error ? error.message : String(error)}`,
+                },
+            ],
+            isError: true,
+        };
+    }
+}
+function isDuplicateError(error) {
+    return (typeof error === "object" &&
+        error !== null &&
+        "statusCode" in error &&
+        error.statusCode === 409);
+}
+function parseDuplicateInfo(error) {
+    try {
+        const body = error.body;
+        if (body) {
+            const parsed = JSON.parse(body);
+            // Handle multiple possible field names the API might use
+            const duplicateOf = parsed.duplicate_of ??
+                parsed.duplicateOf ??
+                parsed.existing_id ??
+                parsed.memory_id ??
+                "unknown";
+            const similarity = parsed.jaccard_similarity ??
+                parsed.similarity ??
+                parsed.score ??
+                0;
+            return { duplicateOf, similarity };
+        }
+    }
+    catch {
+        // ignore parse errors
+    }
+    return { duplicateOf: "unknown", similarity: 0 };
+}
+// ── Tool registration ────────────────────────────────────────────
+export function registerWriteTools(server) {
+    // hivemind_write_instruction
+    server.registerTool("hivemind_write_instruction", {
+        title: "Share What Works",
+        description: INSTRUCTION_DESC,
+        inputSchema: InstructionSchema,
+        outputSchema: WriteOutputSchema,
+        annotations: {
+            readOnlyHint: false,
+            destructiveHint: false,
+            idempotentHint: false,
+            openWorldHint: true,
+        },
+    }, async (params) => {
+        return handleWrite(params, "instruction");
+    });
+    // hivemind_write_mistake
+    server.registerTool("hivemind_write_mistake", {
+        title: "Warn About Failures",
+        description: MISTAKE_DESC,
+        inputSchema: MistakeSchema,
+        outputSchema: WriteOutputSchema,
+        annotations: {
+            readOnlyHint: false,
+            destructiveHint: false,
+            idempotentHint: false,
+            openWorldHint: true,
+        },
+    }, async (params) => {
+        return handleWrite(params, "mistake");
+    });
+    // hivemind_write_update
+    server.registerTool("hivemind_write_update", {
+        title: "Share Factual Changes",
+        description: UPDATE_DESC,
+        inputSchema: UpdateSchema,
+        outputSchema: WriteOutputSchema,
+        annotations: {
+            readOnlyHint: false,
+            destructiveHint: false,
+            idempotentHint: false,
+            openWorldHint: true,
+        },
+    }, async (params) => {
+        return handleWrite(params, "update");
+    });
+}
+//# sourceMappingURL=write.js.map

package/dist/tools/write.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"write.js","sourceRoot":"","sources":["../../src/tools/write.ts"],"names":[],"mappings":"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"}

package/package.json

@@ -0,0 +1,59 @@
+{
+  "name": "bhived-mcp",
+  "version": "1.1.5",
+  "description": "HiveMind MCP Server — shared knowledge graph for AI agents. Query, write, and inspect collective AI knowledge through the Model Context Protocol.",
+  "type": "module",
+  "main": "dist/index.js",
+  "bin": {
+    "bhived-mcp": "dist/index.js"
+  },
+  "files": [
+    "dist",
+    "README.md",
+    "LICENSE"
+  ],
+  "scripts": {
+    "clean": "rimraf dist",
+    "build": "tsc",
+    "dev": "tsx watch src/index.ts",
+    "start": "node dist/index.js",
+    "inspect": "npx @modelcontextprotocol/inspector node dist/index.js",
+    "prepare": "npm run build",
+    "prepublishOnly": "npm run clean && npm run build"
+  },
+  "dependencies": {
+    "@modelcontextprotocol/sdk": "^1.27.1",
+    "express": "^5.2.1",
+    "zod": "^4.3.6"
+  },
+  "devDependencies": {
+    "@types/express": "^5.0.6",
+    "@types/node": "^25.5.0",
+    "rimraf": "^6.0.1",
+    "tsx": "^4.21.0",
+    "typescript": "^5.9.3"
+  },
+  "engines": {
+    "node": ">=18"
+  },
+  "keywords": [
+    "mcp",
+    "mcp-server",
+    "hivemind",
+    "ai-agents",
+    "knowledge-graph",
+    "model-context-protocol",
+    "falkordb",
+    "graph-database"
+  ],
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/your-org/bhived-mcp.git"
+  },
+  "homepage": "https://github.com/your-org/bhived-mcp#readme",
+  "bugs": {
+    "url": "https://github.com/your-org/bhived-mcp/issues"
+  },
+  "author": "ArtKey",
+  "license": "MIT"
+}