geo-mcp-server 1.0.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 Riccardo Esclapon
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,131 @@
+# Geo MCP Server
+
+MCP server providing full access to the [Geo protocol](https://geo.xyz) SDK for knowledge graph operations. Build, query, and publish structured knowledge to the Geo decentralized knowledge network using the [GRC-20](https://github.com/geobrowser/grcs/blob/main/grcs/grc-0020.md) standard.
+
+## Features
+
+- **19 tools** covering the full Geo SDK surface
+- **Session-based op accumulation** - build complex edits across multiple tool calls, then publish as a single atomic transaction
+- **Name-based resolution** - reference properties, types, and entities by name instead of IDs
+- **Gas-sponsored smart accounts** - no testnet ETH needed (uses Pimlico paymaster)
+
+## Installation
+
+```bash
+npm install
+npm run build
+```
+
+## Configuration
+
+Add to your MCP client config (e.g. Claude Code `.mcp.json`):
+
+```json
+{
+  "mcpServers": {
+    "geo": {
+      "command": "node",
+      "args": ["/path/to/geo-mcp-server/dist/index.js"],
+      "env": {
+        "GEO_PRIVATE_KEY": "0x..."
+      }
+    }
+  }
+}
+```
+
+The `GEO_PRIVATE_KEY` environment variable is optional at startup - you can also configure the wallet at runtime using the `configure_wallet` tool.
+
+## Quick Start
+
+Typical workflow:
+
+1. **Configure wallet** - `configure_wallet` with your private key
+2. **Setup space** - `setup_space` creates or finds your personal space
+3. **Build knowledge** - use any graph tools to create properties, types, entities, and relations
+4. **Publish** - `publish_edit` sends all accumulated ops on-chain in one transaction
+
+### Example: Create a Knowledge Graph in One Call
+
+Use `create_knowledge_graph` for the best UX - it builds schema, entities, and relations all at once with name-based references:
+
+```
+create_knowledge_graph({
+  schema: {
+    properties: [
+      { name: "Founded", dataType: "DATE" },
+      { name: "Website", dataType: "TEXT" }
+    ],
+    types: [
+      { name: "Company", propertyNames: ["Founded", "Website"] }
+    ]
+  },
+  entities: [
+    {
+      name: "Geo",
+      typeName: "Company",
+      values: [
+        { propertyName: "Founded", type: "date", value: "2024-01-01" },
+        { propertyName: "Website", type: "text", value: "https://geo.xyz" }
+      ]
+    }
+  ]
+})
+```
+
+## Tools Reference
+
+### Graph Operations (8 tools)
+
+| Tool | Description |
+|------|-------------|
+| `create_property` | Create a property definition with a data type |
+| `create_type` | Create a type (schema) grouping properties |
+| `create_entity` | Create an entity with types, values, and relations |
+| `create_relation` | Create a relation between two entities |
+| `create_image` | Create an image entity from a URL |
+| `update_entity` | Update an existing entity's name, values, or properties |
+| `delete_entity` | Delete an entity |
+| `delete_relation` | Delete a relation |
+
+### Space & Publishing (6 tools)
+
+| Tool | Description |
+|------|-------------|
+| `configure_wallet` | Set up wallet with a private key for publishing |
+| `setup_space` | Create or find your personal space |
+| `publish_edit` | Publish all accumulated ops as one on-chain edit |
+| `propose_dao_edit` | Propose accumulated ops as a DAO governance edit |
+| `get_session_status` | View current session state (ops count, artifacts, wallet) |
+| `clear_session` | Discard all accumulated ops |
+
+### Advanced UX (5 tools)
+
+| Tool | Description |
+|------|-------------|
+| `generate_id` | Generate one or more unique Geo IDs (dashless UUID v4) |
+| `build_schema` | Create properties + types in one call with name-based references |
+| `create_knowledge_graph` | Build complete graph (schema + entities + relations) in one call |
+| `add_values_to_entity` | Add multiple property values to an existing entity |
+| `get_system_ids` | Get well-known Geo system IDs (types, properties, data types) |
+
+### Supported Data Types
+
+`TEXT`, `INTEGER`, `FLOAT`, `BOOLEAN`, `DATE`, `TIME`, `DATETIME`, `SCHEDULE`, `POINT`, `DECIMAL`, `BYTES`, `EMBEDDING`, `RELATION`
+
+## Development
+
+```bash
+npm run dev        # Run with tsx (hot reload)
+npm run build      # Compile TypeScript
+npm run typecheck  # Type check without emitting
+npm start          # Run compiled version
+```
+
+## Network
+
+Currently operates on the Geo **testnet**.
+
+## License
+
+MIT

package/dist/index.d.ts

@@ -0,0 +1,3 @@
+#!/usr/bin/env node
+export {};
+//# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":""}

package/dist/index.js

@@ -0,0 +1,14 @@
+#!/usr/bin/env node
+import { StdioServerTransport } from '@modelcontextprotocol/sdk/server/stdio.js';
+import { createServer } from './server.js';
+async function main() {
+    const server = createServer();
+    const transport = new StdioServerTransport();
+    await server.connect(transport);
+    console.error('Geo MCP server running on stdio');
+}
+main().catch((error) => {
+    console.error('Fatal error:', error);
+    process.exit(1);
+});
+//# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":";AACA,OAAO,EAAE,oBAAoB,EAAE,MAAM,2CAA2C,CAAC;AACjF,OAAO,EAAE,YAAY,EAAE,MAAM,aAAa,CAAC;AAE3C,KAAK,UAAU,IAAI;IACjB,MAAM,MAAM,GAAG,YAAY,EAAE,CAAC;IAC9B,MAAM,SAAS,GAAG,IAAI,oBAAoB,EAAE,CAAC;IAC7C,MAAM,MAAM,CAAC,OAAO,CAAC,SAAS,CAAC,CAAC;IAChC,OAAO,CAAC,KAAK,CAAC,iCAAiC,CAAC,CAAC;AACnD,CAAC;AAED,IAAI,EAAE,CAAC,KAAK,CAAC,CAAC,KAAK,EAAE,EAAE;IACrB,OAAO,CAAC,KAAK,CAAC,cAAc,EAAE,KAAK,CAAC,CAAC;IACrC,OAAO,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC;AAClB,CAAC,CAAC,CAAC"}

package/dist/server.d.ts

@@ -0,0 +1,3 @@
+import { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
+export declare function createServer(): McpServer;
+//# sourceMappingURL=server.d.ts.map

package/dist/server.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"server.d.ts","sourceRoot":"","sources":["../src/server.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,SAAS,EAAE,MAAM,yCAAyC,CAAC;AAMpE,wBAAgB,YAAY,IAAI,SAAS,CAWxC"}

package/dist/server.js

@@ -0,0 +1,16 @@
+import { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
+import { session } from './state/session.js';
+import { registerGraphTools } from './tools/graph.js';
+import { registerSpaceTools } from './tools/spaces.js';
+import { registerAdvancedTools } from './tools/advanced.js';
+export function createServer() {
+    const server = new McpServer({
+        name: 'geo-mcp-server',
+        version: '1.0.0',
+    });
+    registerGraphTools(server, session);
+    registerSpaceTools(server, session);
+    registerAdvancedTools(server, session);
+    return server;
+}
+//# sourceMappingURL=server.js.map

package/dist/server.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"server.js","sourceRoot":"","sources":["../src/server.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,SAAS,EAAE,MAAM,yCAAyC,CAAC;AACpE,OAAO,EAAE,OAAO,EAAE,MAAM,oBAAoB,CAAC;AAC7C,OAAO,EAAE,kBAAkB,EAAE,MAAM,kBAAkB,CAAC;AACtD,OAAO,EAAE,kBAAkB,EAAE,MAAM,mBAAmB,CAAC;AACvD,OAAO,EAAE,qBAAqB,EAAE,MAAM,qBAAqB,CAAC;AAE5D,MAAM,UAAU,YAAY;IAC1B,MAAM,MAAM,GAAG,IAAI,SAAS,CAAC;QAC3B,IAAI,EAAE,gBAAgB;QACtB,OAAO,EAAE,OAAO;KACjB,CAAC,CAAC;IAEH,kBAAkB,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;IACpC,kBAAkB,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;IACpC,qBAAqB,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;IAEvC,OAAO,MAAM,CAAC;AAChB,CAAC"}

package/dist/state/session.d.ts

@@ -0,0 +1,39 @@
+/**
+ * Edit session state management for the Geo MCP server.
+ * Manages op accumulation across tool calls and tracks created artifacts.
+ */
+import type { Op } from '@geoprotocol/grc-20';
+export interface CreatedArtifact {
+    id: string;
+    type: 'property' | 'type' | 'entity' | 'relation' | 'image';
+    name: string;
+    opsCount: number;
+}
+export interface SessionStatus {
+    opsCount: number;
+    artifacts: CreatedArtifact[];
+    walletConfigured: boolean;
+    spaceId: string | null;
+    network: 'TESTNET';
+}
+export declare class EditSession {
+    private ops;
+    private artifacts;
+    private _privateKey;
+    private _spaceId;
+    private _walletAddress;
+    addOps(ops: Op[], artifact: CreatedArtifact): void;
+    getOps(): Op[];
+    getArtifacts(): CreatedArtifact[];
+    clear(): void;
+    get opsCount(): number;
+    get privateKey(): string | null;
+    set privateKey(key: string | null);
+    get spaceId(): string | null;
+    set spaceId(id: string | null);
+    get walletAddress(): string | null;
+    set walletAddress(address: string | null);
+    getStatus(): SessionStatus;
+}
+export declare const session: EditSession;
+//# sourceMappingURL=session.d.ts.map

package/dist/state/session.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"session.d.ts","sourceRoot":"","sources":["../../src/state/session.ts"],"names":[],"mappings":"AAAA;;;GAGG;AACH,OAAO,KAAK,EAAE,EAAE,EAAE,MAAM,qBAAqB,CAAC;AAE9C,MAAM,WAAW,eAAe;IAC9B,EAAE,EAAE,MAAM,CAAC;IACX,IAAI,EAAE,UAAU,GAAG,MAAM,GAAG,QAAQ,GAAG,UAAU,GAAG,OAAO,CAAC;IAC5D,IAAI,EAAE,MAAM,CAAC;IACb,QAAQ,EAAE,MAAM,CAAC;CAClB;AAED,MAAM,WAAW,aAAa;IAC5B,QAAQ,EAAE,MAAM,CAAC;IACjB,SAAS,EAAE,eAAe,EAAE,CAAC;IAC7B,gBAAgB,EAAE,OAAO,CAAC;IAC1B,OAAO,EAAE,MAAM,GAAG,IAAI,CAAC;IACvB,OAAO,EAAE,SAAS,CAAC;CACpB;AAED,qBAAa,WAAW;IACtB,OAAO,CAAC,GAAG,CAAY;IACvB,OAAO,CAAC,SAAS,CAAyB;IAC1C,OAAO,CAAC,WAAW,CAAuB;IAC1C,OAAO,CAAC,QAAQ,CAAuB;IACvC,OAAO,CAAC,cAAc,CAAuB;IAE7C,MAAM,CAAC,GAAG,EAAE,EAAE,EAAE,EAAE,QAAQ,EAAE,eAAe,GAAG,IAAI;IAKlD,MAAM,IAAI,EAAE,EAAE;IAId,YAAY,IAAI,eAAe,EAAE;IAIjC,KAAK,IAAI,IAAI;IAKb,IAAI,QAAQ,IAAI,MAAM,CAErB;IAED,IAAI,UAAU,IAAI,MAAM,GAAG,IAAI,CAE9B;IAED,IAAI,UAAU,CAAC,GAAG,EAAE,MAAM,GAAG,IAAI,EAEhC;IAED,IAAI,OAAO,IAAI,MAAM,GAAG,IAAI,CAE3B;IAED,IAAI,OAAO,CAAC,EAAE,EAAE,MAAM,GAAG,IAAI,EAE5B;IAED,IAAI,aAAa,IAAI,MAAM,GAAG,IAAI,CAEjC;IAED,IAAI,aAAa,CAAC,OAAO,EAAE,MAAM,GAAG,IAAI,EAEvC;IAED,SAAS,IAAI,aAAa;CAS3B;AAGD,eAAO,MAAM,OAAO,aAAoB,CAAC"}

package/dist/state/session.js

@@ -0,0 +1,54 @@
+export class EditSession {
+    ops = [];
+    artifacts = [];
+    _privateKey = null;
+    _spaceId = null;
+    _walletAddress = null;
+    addOps(ops, artifact) {
+        this.ops.push(...ops);
+        this.artifacts.push(artifact);
+    }
+    getOps() {
+        return [...this.ops];
+    }
+    getArtifacts() {
+        return [...this.artifacts];
+    }
+    clear() {
+        this.ops = [];
+        this.artifacts = [];
+    }
+    get opsCount() {
+        return this.ops.length;
+    }
+    get privateKey() {
+        return this._privateKey;
+    }
+    set privateKey(key) {
+        this._privateKey = key;
+    }
+    get spaceId() {
+        return this._spaceId;
+    }
+    set spaceId(id) {
+        this._spaceId = id;
+    }
+    get walletAddress() {
+        return this._walletAddress;
+    }
+    set walletAddress(address) {
+        this._walletAddress = address;
+    }
+    getStatus() {
+        return {
+            opsCount: this.ops.length,
+            artifacts: [...this.artifacts],
+            walletConfigured: this._privateKey !== null,
+            spaceId: this._spaceId,
+            network: 'TESTNET',
+        };
+    }
+}
+// Singleton session instance
+export const session = new EditSession();
+//# sourceMappingURL=session.js.map

package/dist/state/session.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"session.js","sourceRoot":"","sources":["../../src/state/session.ts"],"names":[],"mappings":"AAqBA,MAAM,OAAO,WAAW;IACd,GAAG,GAAS,EAAE,CAAC;IACf,SAAS,GAAsB,EAAE,CAAC;IAClC,WAAW,GAAkB,IAAI,CAAC;IAClC,QAAQ,GAAkB,IAAI,CAAC;IAC/B,cAAc,GAAkB,IAAI,CAAC;IAE7C,MAAM,CAAC,GAAS,EAAE,QAAyB;QACzC,IAAI,CAAC,GAAG,CAAC,IAAI,CAAC,GAAG,GAAG,CAAC,CAAC;QACtB,IAAI,CAAC,SAAS,CAAC,IAAI,CAAC,QAAQ,CAAC,CAAC;IAChC,CAAC;IAED,MAAM;QACJ,OAAO,CAAC,GAAG,IAAI,CAAC,GAAG,CAAC,CAAC;IACvB,CAAC;IAED,YAAY;QACV,OAAO,CAAC,GAAG,IAAI,CAAC,SAAS,CAAC,CAAC;IAC7B,CAAC;IAED,KAAK;QACH,IAAI,CAAC,GAAG,GAAG,EAAE,CAAC;QACd,IAAI,CAAC,SAAS,GAAG,EAAE,CAAC;IACtB,CAAC;IAED,IAAI,QAAQ;QACV,OAAO,IAAI,CAAC,GAAG,CAAC,MAAM,CAAC;IACzB,CAAC;IAED,IAAI,UAAU;QACZ,OAAO,IAAI,CAAC,WAAW,CAAC;IAC1B,CAAC;IAED,IAAI,UAAU,CAAC,GAAkB;QAC/B,IAAI,CAAC,WAAW,GAAG,GAAG,CAAC;IACzB,CAAC;IAED,IAAI,OAAO;QACT,OAAO,IAAI,CAAC,QAAQ,CAAC;IACvB,CAAC;IAED,IAAI,OAAO,CAAC,EAAiB;QAC3B,IAAI,CAAC,QAAQ,GAAG,EAAE,CAAC;IACrB,CAAC;IAED,IAAI,aAAa;QACf,OAAO,IAAI,CAAC,cAAc,CAAC;IAC7B,CAAC;IAED,IAAI,aAAa,CAAC,OAAsB;QACtC,IAAI,CAAC,cAAc,GAAG,OAAO,CAAC;IAChC,CAAC;IAED,SAAS;QACP,OAAO;YACL,QAAQ,EAAE,IAAI,CAAC,GAAG,CAAC,MAAM;YACzB,SAAS,EAAE,CAAC,GAAG,IAAI,CAAC,SAAS,CAAC;YAC9B,gBAAgB,EAAE,IAAI,CAAC,WAAW,KAAK,IAAI;YAC3C,OAAO,EAAE,IAAI,CAAC,QAAQ;YACtB,OAAO,EAAE,SAAS;SACnB,CAAC;IACJ,CAAC;CACF;AAED,6BAA6B;AAC7B,MAAM,CAAC,MAAM,OAAO,GAAG,IAAI,WAAW,EAAE,CAAC"}

package/dist/tools/advanced.d.ts

@@ -0,0 +1,8 @@
+/**
+ * Advanced high-level MCP tools that combine multiple SDK operations
+ * for a better UX experience.
+ */
+import { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
+import type { EditSession } from '../state/session.js';
+export declare function registerAdvancedTools(server: McpServer, session: EditSession): void;
+//# sourceMappingURL=advanced.d.ts.map

package/dist/tools/advanced.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"advanced.d.ts","sourceRoot":"","sources":["../../src/tools/advanced.ts"],"names":[],"mappings":"AAAA;;;GAGG;AACH,OAAO,EAAE,SAAS,EAAE,MAAM,yCAAyC,CAAC;AAGpE,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,qBAAqB,CAAC;AAEvD,wBAAgB,qBAAqB,CAAC,MAAM,EAAE,SAAS,EAAE,OAAO,EAAE,WAAW,GAAG,IAAI,CAghBnF"}