cograph-mcp 0.1.0

package/README.md

@@ -0,0 +1,47 @@
+# cograph-mcp
+
+MCP (Model Context Protocol) server for [Cograph](https://cograph.cloud). Gives AI agents tools to query and ingest data into your knowledge graphs.
+
+## Install / run
+
+No install needed — use `npx`:
+
+```bash
+npx -y cograph-mcp
+```
+
+## Claude Desktop / Cursor / Claude Code
+
+```json
+{
+  "mcpServers": {
+    "cograph": {
+      "command": "npx",
+      "args": ["-y", "cograph-mcp"],
+      "env": {
+        "COGRAPH_API_KEY": "your-key",
+        "COGRAPH_API_URL": "https://api.cograph.cloud"
+      }
+    }
+  }
+}
+```
+
+## Tools exposed
+
+- `list_knowledge_graphs` — list available KGs and descriptions
+- `ask` — ask a natural language question; returns the answer
+- `ingest_csv` — ingest a CSV file by absolute path into a named KG
+- `view_ontology` — show types, attributes, relationships across KGs
+
+## Environment
+
+- `COGRAPH_API_KEY` — required
+- `COGRAPH_API_URL` — default `https://api.cograph.cloud`
+- `COGRAPH_TENANT` — default `demo-tenant`
+
+Legacy `OMNIX_*` vars are also accepted.
+
+## License
+
+MIT

package/dist/index.js

@@ -0,0 +1,151 @@
+#!/usr/bin/env node
+
+// src/index.ts
+import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
+import { Client, CographError } from "cograph";
+import { z } from "zod";
+var VERSION = "0.1.0";
+var server = new McpServer(
+  {
+    name: "cograph",
+    version: VERSION
+  },
+  {
+    instructions: "Cograph is a knowledge graph platform. Use these tools to query structured data across multiple knowledge graphs using natural language."
+  }
+);
+function client() {
+  return new Client();
+}
+function textResult(text) {
+  return {
+    content: [{ type: "text", text }]
+  };
+}
+function errorResult(err) {
+  const msg = err instanceof CographError ? `Cograph error: ${err.message}` : err instanceof Error ? err.message : String(err);
+  return {
+    content: [{ type: "text", text: msg }],
+    isError: true
+  };
+}
+server.registerTool(
+  "list_knowledge_graphs",
+  {
+    description: "List all available knowledge graphs and their descriptions.",
+    inputSchema: {}
+  },
+  async () => {
+    try {
+      const kgs = await client().listKgs();
+      if (!kgs.length) return textResult("No knowledge graphs found.");
+      const lines = kgs.map((kg) => {
+        const name = String(kg.name ?? "?");
+        const desc = kg.description ? `: ${kg.description}` : "";
+        return `- ${name}${desc}`;
+      });
+      return textResult(lines.join("\n"));
+    } catch (err) {
+      return errorResult(err);
+    }
+  }
+);
+server.registerTool(
+  "ask",
+  {
+    description: "Ask a natural language question against a knowledge graph. Use list_knowledge_graphs to see available KGs first.",
+    inputSchema: {
+      question: z.string().describe(
+        'The natural language question to ask (e.g., "How many events are in San Francisco?")'
+      ),
+      kg_name: z.string().optional().describe(
+        "Name of the knowledge graph to query. Use list_knowledge_graphs to see available KGs."
+      )
+    }
+  },
+  async ({ question, kg_name }) => {
+    try {
+      const data = await client().ask(question, { kg: kg_name });
+      const answer = data.answer ?? "No answer";
+      const explanation = data.explanation;
+      let out = `Answer: ${answer}`;
+      if (explanation) out += `
+Explanation: ${explanation}`;
+      return textResult(out);
+    } catch (err) {
+      return errorResult(err);
+    }
+  }
+);
+server.registerTool(
+  "ingest_csv",
+  {
+    description: "Ingest a CSV file into a knowledge graph. The schema is automatically inferred.",
+    inputSchema: {
+      file_path: z.string().describe("Absolute path to the CSV file to ingest."),
+      kg_name: z.string().describe(
+        'Name for the knowledge graph (e.g., "sales-data", "customer-records").'
+      )
+    }
+  },
+  async ({ file_path, kg_name }) => {
+    try {
+      const result = await client().ingest(file_path, { kg: kg_name });
+      const entities = Number(result.entities_resolved ?? 0);
+      const triples = Number(result.triples_inserted ?? 0);
+      return textResult(
+        `Ingestion complete: ${entities} entities resolved, ${triples} triples inserted into "${kg_name}".`
+      );
+    } catch (err) {
+      return errorResult(err);
+    }
+  }
+);
+server.registerTool(
+  "view_ontology",
+  {
+    description: "View the ontology (types, attributes, relationships) across all knowledge graphs.",
+    inputSchema: {}
+  },
+  async () => {
+    try {
+      const types = await client().ontologyTypes();
+      if (!types.length) return textResult("No ontology types defined yet.");
+      const lines = [];
+      for (const t of types) {
+        const name = String(t.name ?? "?");
+        lines.push(`Type: ${name}`);
+        const attrs = t.attributes ?? [];
+        if (attrs.length) {
+          lines.push(
+            `  Attributes: ${attrs.map((a) => String(a.name ?? "?")).join(", ")}`
+          );
+        }
+        const rels = t.relationships ?? [];
+        if (rels.length) {
+          lines.push(
+            `  Relationships: ${rels.map(
+              (r) => `${String(r.predicate ?? "?")} -> ${String(r.target_type ?? "?")}`
+            ).join(", ")}`
+          );
+        }
+      }
+      return textResult(lines.join("\n"));
+    } catch (err) {
+      return errorResult(err);
+    }
+  }
+);
+async function main() {
+  const transport = new StdioServerTransport();
+  await server.connect(transport);
+}
+main().catch((err) => {
+  process.stderr.write(
+    `cograph-mcp failed to start: ${err instanceof Error ? err.message : String(err)}
+`
+  );
+  process.exit(1);
+});
+//# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../src/index.ts"],"sourcesContent":["import { McpServer } from \"@modelcontextprotocol/sdk/server/mcp.js\";\nimport { StdioServerTransport } from \"@modelcontextprotocol/sdk/server/stdio.js\";\nimport { Client, CographError } from \"cograph\";\nimport { z } from \"zod\";\n\nconst VERSION = \"0.1.0\";\n\nconst server = new McpServer(\n  {\n    name: \"cograph\",\n    version: VERSION,\n  },\n  {\n    instructions:\n      \"Cograph is a knowledge graph platform. Use these tools to query \" +\n      \"structured data across multiple knowledge graphs using natural language.\",\n  },\n);\n\nfunction client(): Client {\n  return new Client();\n}\n\nfunction textResult(text: string) {\n  return {\n    content: [{ type: \"text\" as const, text }],\n  };\n}\n\nfunction errorResult(err: unknown) {\n  const msg =\n    err instanceof CographError\n      ? `Cograph error: ${err.message}`\n      : err instanceof Error\n        ? err.message\n        : String(err);\n  return {\n    content: [{ type: \"text\" as const, text: msg }],\n    isError: true,\n  };\n}\n\nserver.registerTool(\n  \"list_knowledge_graphs\",\n  {\n    description:\n      \"List all available knowledge graphs and their descriptions.\",\n    inputSchema: {},\n  },\n  async () => {\n    try {\n      const kgs = await client().listKgs();\n      if (!kgs.length) return textResult(\"No knowledge graphs found.\");\n      const lines = kgs.map((kg) => {\n        const name = String(kg.name ?? \"?\");\n        const desc = kg.description ? `: ${kg.description}` : \"\";\n        return `- ${name}${desc}`;\n      });\n      return textResult(lines.join(\"\\n\"));\n    } catch (err) {\n      return errorResult(err);\n    }\n  },\n);\n\nserver.registerTool(\n  \"ask\",\n  {\n    description:\n      \"Ask a natural language question against a knowledge graph. \" +\n      'Use list_knowledge_graphs to see available KGs first.',\n    inputSchema: {\n      question: z\n        .string()\n        .describe(\n          'The natural language question to ask (e.g., \"How many events are in San Francisco?\")',\n        ),\n      kg_name: z\n        .string()\n        .optional()\n        .describe(\n          \"Name of the knowledge graph to query. Use list_knowledge_graphs to see available KGs.\",\n        ),\n    },\n  },\n  async ({ question, kg_name }) => {\n    try {\n      const data = await client().ask(question, { kg: kg_name });\n      const answer = data.answer ?? \"No answer\";\n      const explanation = data.explanation;\n      let out = `Answer: ${answer}`;\n      if (explanation) out += `\\nExplanation: ${explanation}`;\n      return textResult(out);\n    } catch (err) {\n      return errorResult(err);\n    }\n  },\n);\n\nserver.registerTool(\n  \"ingest_csv\",\n  {\n    description:\n      \"Ingest a CSV file into a knowledge graph. The schema is automatically inferred.\",\n    inputSchema: {\n      file_path: z\n        .string()\n        .describe(\"Absolute path to the CSV file to ingest.\"),\n      kg_name: z\n        .string()\n        .describe(\n          'Name for the knowledge graph (e.g., \"sales-data\", \"customer-records\").',\n        ),\n    },\n  },\n  async ({ file_path, kg_name }) => {\n    try {\n      const result = await client().ingest(file_path, { kg: kg_name });\n      const entities = Number(result.entities_resolved ?? 0);\n      const triples = Number(result.triples_inserted ?? 0);\n      return textResult(\n        `Ingestion complete: ${entities} entities resolved, ${triples} triples inserted into \"${kg_name}\".`,\n      );\n    } catch (err) {\n      return errorResult(err);\n    }\n  },\n);\n\nserver.registerTool(\n  \"view_ontology\",\n  {\n    description:\n      \"View the ontology (types, attributes, relationships) across all knowledge graphs.\",\n    inputSchema: {},\n  },\n  async () => {\n    try {\n      const types = await client().ontologyTypes();\n      if (!types.length) return textResult(\"No ontology types defined yet.\");\n      const lines: string[] = [];\n      for (const t of types) {\n        const name = String(t.name ?? \"?\");\n        lines.push(`Type: ${name}`);\n        const attrs = (t.attributes ?? []) as Array<Record<string, unknown>>;\n        if (attrs.length) {\n          lines.push(\n            `  Attributes: ${attrs.map((a) => String(a.name ?? \"?\")).join(\", \")}`,\n          );\n        }\n        const rels = (t.relationships ?? []) as Array<Record<string, unknown>>;\n        if (rels.length) {\n          lines.push(\n            `  Relationships: ${rels\n              .map(\n                (r) =>\n                  `${String(r.predicate ?? \"?\")} -> ${String(r.target_type ?? \"?\")}`,\n              )\n              .join(\", \")}`,\n          );\n        }\n      }\n      return textResult(lines.join(\"\\n\"));\n    } catch (err) {\n      return errorResult(err);\n    }\n  },\n);\n\nasync function main(): Promise<void> {\n  const transport = new StdioServerTransport();\n  await server.connect(transport);\n}\n\nmain().catch((err) => {\n  process.stderr.write(\n    `cograph-mcp failed to start: ${err instanceof Error ? err.message : String(err)}\\n`,\n  );\n  process.exit(1);\n});\n"],"mappings":"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","names":[]}

package/package.json

@@ -0,0 +1,46 @@
+{
+  "name": "cograph-mcp",
+  "version": "0.1.0",
+  "description": "Cograph MCP server — expose knowledge graph tools to AI agents",
+  "type": "module",
+  "main": "./dist/index.js",
+  "bin": {
+    "cograph-mcp": "./dist/index.js"
+  },
+  "files": [
+    "dist",
+    "README.md"
+  ],
+  "scripts": {
+    "build": "tsup",
+    "prepack": "node ../../scripts/chmod-bin.js packages/cograph-mcp/dist/index.js"
+  },
+  "keywords": [
+    "knowledge-graph",
+    "cograph",
+    "mcp",
+    "model-context-protocol",
+    "ai",
+    "llm",
+    "agent"
+  ],
+  "author": "Cograph",
+  "license": "MIT",
+  "homepage": "https://cograph.cloud",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/git-moeen/cograph-oss.git",
+    "directory": "packages/cograph-mcp"
+  },
+  "bugs": {
+    "url": "https://github.com/git-moeen/cograph-oss/issues"
+  },
+  "dependencies": {
+    "cograph": "^0.1.0",
+    "@modelcontextprotocol/sdk": "^1.0.4",
+    "zod": "^3.23.8"
+  },
+  "engines": {
+    "node": ">=20"
+  }
+}