@kubun/mcp 0.1.0

package/LICENSE.md

@@ -0,0 +1,57 @@
+# The Prosperity Public License 3.0.0
+
+Contributor: Paul Le Cam
+
+Source Code: https://github.com/PaulLeCam/kubun
+
+## Purpose
+
+This license allows you to use and share this software for noncommercial purposes for free and to try this software for commercial purposes for thirty days.
+
+## Agreement
+
+In order to receive this license, you have to agree to its rules.  Those rules are both obligations under that agreement and conditions to your license.  Don't do anything with this software that triggers a rule you can't or won't follow.
+
+## Notices
+
+Make sure everyone who gets a copy of any part of this software from you, with or without changes, also gets the text of this license and the contributor and source code lines above.
+
+## Commercial Trial
+
+Limit your use of this software for commercial purposes to a thirty-day trial period.  If you use this software for work, your company gets one trial period for all personnel, not one trial per person.
+
+## Contributions Back
+
+Developing feedback, changes, or additions that you contribute back to the contributor on the terms of a standardized public software license such as [the Blue Oak Model License 1.0.0](https://blueoakcouncil.org/license/1.0.0), [the Apache License 2.0](https://www.apache.org/licenses/LICENSE-2.0.html), [the MIT license](https://spdx.org/licenses/MIT.html), or [the two-clause BSD license](https://spdx.org/licenses/BSD-2-Clause.html) doesn't count as use for a commercial purpose.
+
+## Personal Uses
+
+Personal use for research, experiment, and testing for the benefit of public knowledge, personal study, private entertainment, hobby projects, amateur pursuits, or religious observance, without any anticipated commercial application, doesn't count as use for a commercial purpose.
+
+## Noncommercial Organizations
+
+Use by any charitable organization, educational institution, public research organization, public safety or health organization, environmental protection organization, or government institution doesn't count as use for a commercial purpose regardless of the source of funding or obligations resulting from the funding.
+
+## Defense
+
+Don't make any legal claim against anyone accusing this software, with or without changes, alone or with other technology, of infringing any patent.
+
+## Copyright
+
+The contributor licenses you to do everything with this software that would otherwise infringe their copyright in it.
+
+## Patent
+
+The contributor licenses you to do everything with this software that would otherwise infringe any patents they can license or become able to license.
+
+## Reliability
+
+The contributor can't revoke this license.
+
+## Excuse
+
+You're excused for unknowingly breaking [Notices](#notices) if you take all practical steps to comply within thirty days of learning you broke the rule.
+
+## No Liability
+
+***As far as the law allows, this software comes as is, without any warranty or condition, and the contributor won't be liable to anyone for any damages related to this software or this license, under any kind of legal claim.***

package/lib/client.d.ts

@@ -0,0 +1,20 @@
+import { type TokenSigner } from '@enkaku/token';
+import type { KubunClient } from '@kubun/client';
+export type ClientConfig = {
+    type: 'memory';
+} | {
+    type: 'sqlite';
+    path: string;
+} | {
+    type: 'postgres';
+    url: string;
+} | {
+    type: 'http';
+    url: string;
+    serverID?: string;
+};
+export type ClientParams = ClientConfig & {
+    signer?: TokenSigner;
+};
+export declare function createClient(params: ClientParams): KubunClient;
+//# sourceMappingURL=client.d.ts.map

package/lib/client.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"client.d.ts","sourceRoot":"","sources":["../src/client.ts"],"names":[],"mappings":"AAAA,OAAO,EAAqB,KAAK,WAAW,EAAE,MAAM,eAAe,CAAA;AACnE,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,eAAe,CAAA;AAOhD,MAAM,MAAM,YAAY,GACpB;IAAE,IAAI,EAAE,QAAQ,CAAA;CAAE,GAClB;IAAE,IAAI,EAAE,QAAQ,CAAC;IAAC,IAAI,EAAE,MAAM,CAAA;CAAE,GAChC;IAAE,IAAI,EAAE,UAAU,CAAC;IAAC,GAAG,EAAE,MAAM,CAAA;CAAE,GACjC;IAAE,IAAI,EAAE,MAAM,CAAC;IAAC,GAAG,EAAE,MAAM,CAAC;IAAC,QAAQ,CAAC,EAAE,MAAM,CAAA;CAAE,CAAA;AACpD,MAAM,MAAM,YAAY,GAAG,YAAY,GAAG;IAAE,MAAM,CAAC,EAAE,WAAW,CAAA;CAAE,CAAA;AAElE,wBAAgB,YAAY,CAAC,MAAM,EAAE,YAAY,GAAG,WAAW,CAkB9D"}

package/lib/client.js

@@ -0,0 +1,31 @@
+import { randomTokenSigner } from '@enkaku/token';
+import { KubunDB } from '@kubun/db';
+import { PostgresAdapter } from '@kubun/db-postgres';
+import { SQLiteAdapter } from '@kubun/db-sqlite';
+import { HTTPClient } from '@kubun/http-client';
+import { KubunServer } from '@kubun/server';
+export function createClient(params) {
+    const signer = params.signer ?? randomTokenSigner();
+    if (params.type === 'http') {
+        return new HTTPClient({
+            url: params.url,
+            signer,
+            serverID: params.serverID
+        });
+    }
+    const adapter = params.type === 'postgres' ? new PostgresAdapter({
+        url: params.url
+    }) : new SQLiteAdapter({
+        database: params.type === 'sqlite' ? params.path : ':memory:'
+    });
+    const db = new KubunDB({
+        adapter
+    });
+    const server = new KubunServer({
+        db,
+        id: signer.id
+    });
+    return server.createClient({
+        signer
+    });
+}

package/lib/config.d.ts

@@ -0,0 +1,9 @@
+import type { TokenSigner } from '@enkaku/token';
+import type { ServerConfig } from '@mokei/context-server';
+export type MCPConfig = {
+    connect?: string;
+    database?: string;
+    signer?: TokenSigner;
+};
+export declare function createConfig(config?: MCPConfig): ServerConfig;
+//# sourceMappingURL=config.d.ts.map

package/lib/config.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"config.d.ts","sourceRoot":"","sources":["../src/config.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,eAAe,CAAA;AAChD,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,uBAAuB,CAAA;AAOzD,MAAM,MAAM,SAAS,GAAG;IACtB,OAAO,CAAC,EAAE,MAAM,CAAA;IAChB,QAAQ,CAAC,EAAE,MAAM,CAAA;IACjB,MAAM,CAAC,EAAE,WAAW,CAAA;CACrB,CAAA;AAeD,wBAAgB,YAAY,CAAC,MAAM,GAAE,SAAc,GAAG,YAAY,CAcjE"}

package/lib/config.js

@@ -0,0 +1,45 @@
+import { createClient } from './client.js';
+import { prompts } from './prompts/index.js';
+import { createClusterTools } from './tools/cluster.js';
+import { createGraphTools } from './tools/graph.js';
+function parseConfig(config) {
+    if (config.connect != null) {
+        return {
+            type: 'http',
+            url: config.connect,
+            signer: config.signer
+        };
+    }
+    if (config.database != null) {
+        if (config.database.startsWith('postgres://')) {
+            return {
+                type: 'postgres',
+                url: config.database,
+                signer: config.signer
+            };
+        }
+        return {
+            type: 'sqlite',
+            path: config.database,
+            signer: config.signer
+        };
+    }
+    return {
+        type: 'memory',
+        signer: config.signer
+    };
+}
+export function createConfig(config = {}) {
+    const client = createClient(parseConfig(config));
+    const clusterTools = createClusterTools(client);
+    const graphTools = createGraphTools(client);
+    return {
+        name: 'kubun',
+        version: '0.1.0',
+        prompts,
+        tools: {
+            ...clusterTools,
+            ...graphTools
+        }
+    };
+}

package/lib/index.d.ts

@@ -0,0 +1,3 @@
+export { type ClientParams, createClient } from './client.js';
+export { createConfig, type MCPConfig } from './config.js';
+//# sourceMappingURL=index.d.ts.map

package/lib/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,KAAK,YAAY,EAAE,YAAY,EAAE,MAAM,aAAa,CAAA;AAC7D,OAAO,EAAE,YAAY,EAAE,KAAK,SAAS,EAAE,MAAM,aAAa,CAAA"}

package/lib/index.js

@@ -0,0 +1,2 @@
+export { createClient } from './client.js';
+export { createConfig } from './config.js';

package/lib/prompts/data-model-designer.d.ts

@@ -0,0 +1,2 @@
+export declare const KUBUN_PROMPT_INSTRUCTIONS = "# Kubun Protocol Data Model Generator\n\nYou are an expert at creating data models following the Kubun protocol specification. Your task is to generate valid JSON schemas for data models based on user requirements.\n\n## Core Principles\n\n**Automatic Server Fields (DO NOT INCLUDE):**\n- `id` - Server generates globally unique DocID automatically\n- `createdAt` - Server generates timestamp automatically\n- `updatedAt` - Server generates timestamp automatically\n- Owner relations - Server handles user/owner associations automatically\n\n**Model Behaviors:**\n- `default` - Standard concrete models for real entities\n- `interface` - Abstract contracts that other models implement\n- `unique` - Models with uniqueness constraints on specific fields\n\n---\n\n## Built-in Interfaces\n\n### Node (Implicit Base Interface)\n\n**All models implicitly implement the `Node` interface.** This is the base interface for all documents in the system.\n\n- **DO NOT** create a `Node` interface model\n- **DO NOT** include `\"Node\"` in any model's `interfaces` array\n- **DO** use `null` as a `relationModel` value when a field can reference any document\n\n**Example - Field that can link to any document:**\n```json\n{\n  \"fieldsMeta\": {\n    \"linkedItemId\": {\n      \"relationModel\": null\n    }\n  }\n}\n```\n\n---\n\n## Schema Structure\n\nEach model must include:\n```json\n{\n  \"name\": \"PascalCaseModelName\",\n  \"version\": \"1.0\",\n  \"interfaces\": [],\n  \"schema\": { /* JSON Schema definition */ },\n  \"fieldsMeta\": { /* DocID field metadata */ },\n  \"behavior\": \"default|interface|unique\",\n  \"uniqueFields\": [\"field1\", \"field2\"]\n}\n```\n\n| Field | Required | Description |\n|-------|----------|-------------|\n| `name` | Yes | PascalCase model name |\n| `version` | Yes | Schema version (use `\"1.0\"`) |\n| `interfaces` | Yes | Array of interface references (see Interface References) |\n| `schema` | Yes | JSON Schema definition |\n| `fieldsMeta` | Yes | DocID field relationship metadata (can be empty `{}`) |\n| `behavior` | Yes | One of: `default`, `interface`, `unique` |\n| `uniqueFields` | Only for `unique` behavior | Array of field names that must be unique |\n\n---\n\n## Interface References\n\nThe `interfaces` array specifies which interfaces a model implements. Reference format depends on where the interface is defined:\n\n| Interface Location | Reference Format | Example |\n|--------------------|------------------|---------|\n| Existing in database | Model ID | `\"k1a2b3c4d5e6f7g8h9\"` |\n| In same cluster being generated | Array index | `\"#0\"` |\n\n**Rules:**\n- All models implicitly implement `Node` - never include it in the interfaces array\n- When generating a new cluster, define interface models FIRST (at lower indices) so concrete models can reference them\n- Use `#N` format where N is the zero-based array index of the interface model in the cluster\n\n**Example - Model implementing cluster interfaces:**\n```json\n{\n  \"name\": \"Task\",\n  \"interfaces\": [\"#0\", \"#2\"],\n  ...\n}\n```\n\n---\n\n## Relations Between Models\n\nUse `fieldsMeta` to define DocID relationships:\n\n| Target Location | Reference Format | Description |\n|-----------------|------------------|-------------|\n| Any document (polymorphic to Node) | `null` | Field can link to any item in the system |\n| Existing in database | Model ID | `\"k1a2b3c4d5e6f7g8h9\"` |\n| In same cluster being generated | Array index | `\"#2\"` |\n\n**Example:**\n```json\n{\n  \"fieldsMeta\": {\n    \"taskListId\": {\n      \"relationModel\": \"#5\"\n    },\n    \"categoryId\": {\n      \"relationModel\": \"k1a2b3c4d5e6f7g8h9\"\n    },\n    \"linkedItemId\": {\n      \"relationModel\": null\n    }\n  }\n}\n```\n\n---\n\n## Naming Conventions\n\n| Element | Convention | Example |\n|---------|------------|---------|\n| Model names | PascalCase starting with uppercase | `UserProfile`, `BlogPost` |\n| Field names | camelCase starting with lowercase | `firstName`, `createdDate` |\n| Type titles | PascalCase | `EmailAddress`, `PhoneNumber` |\n| Enum values | UPPERCASE_UNDERSCORE | `ACTIVE`, `PENDING_APPROVAL` |\n\n---\n\n## Available Data Types\n\n### Predefined Types (Use When Applicable)\n\nWhen a predefined type matches your use case, copy its exact definition into the `definitions` section and reference it. Never create custom types that duplicate predefined functionality.\n\n| Type | Purpose |\n|------|---------|\n| `AttachmentID` | File/media references |\n| `BigInt` | Large integers |\n| `DateTime` | ISO 8601 date-time |\n| `DID` | Decentralized identifiers |\n| `DocID` | Document references |\n| `Duration` | ISO 8601 duration |\n| `JSONObject` | Flexible JSON data |\n| `Latitude` / `Longitude` | Geographic coordinates |\n| `LocalDate` | Date without time (YYYY-MM-DD) |\n| `LocalDateTime` | Local date-time |\n| `LocalTime` | Time without date |\n| `Locale` | Language/region codes |\n| `TimeZone` | Timezone identifiers |\n| `URL` | Web addresses |\n| `UtcOffset` | UTC time offsets |\n\n**Usage Pattern:**\n```json\n{\n  \"properties\": {\n    \"scheduledAt\": { \"$ref\": \"#/definitions/DateTime\" }\n  },\n  \"definitions\": {\n    \"DateTime\": { \"type\": \"string\", \"format\": \"date-time\", \"title\": \"DateTime\" }\n  }\n}\n```\n\n### Primitive Types\n\n| Type | Variants |\n|------|----------|\n| `boolean` | True/false values |\n| `integer` | Whole numbers (with optional min/max) |\n| `number` | Decimal numbers (with optional min/max) |\n| `string` | Plain text, `const`, `pattern`, `enum`, `format` |\n\n### Complex Types\n\n| Type | Description |\n|------|-------------|\n| `array` | Collections of items |\n| `object` | Structured data with properties |\n\n---\n\n## Example Patterns\n\n### Interface Model\n```json\n{\n  \"name\": \"Completable\",\n  \"version\": \"1.0\",\n  \"interfaces\": [],\n  \"behavior\": \"interface\",\n  \"schema\": {\n    \"type\": \"object\",\n    \"properties\": {\n      \"completed\": { \"$ref\": \"#/definitions/Completed\" },\n      \"completedAt\": { \"$ref\": \"#/definitions/DateTime\" }\n    },\n    \"required\": [\"completed\"],\n    \"additionalProperties\": true,\n    \"definitions\": {\n      \"Completed\": { \"type\": \"boolean\", \"title\": \"Completed\", \"default\": false },\n      \"DateTime\": { \"type\": \"string\", \"format\": \"date-time\", \"title\": \"DateTime\" }\n    }\n  },\n  \"fieldsMeta\": {}\n}\n```\n\n**Note:** Interface schemas use `\"additionalProperties\": true` to allow implementing models to add fields.\n\n### Concrete Model (Implementing Interfaces)\n```json\n{\n  \"name\": \"Task\",\n  \"version\": \"1.0\",\n  \"interfaces\": [\"#0\", \"#1\"],\n  \"behavior\": \"default\",\n  \"schema\": {\n    \"type\": \"object\",\n    \"properties\": {\n      \"title\": { \"$ref\": \"#/definitions/Title\" },\n      \"description\": { \"$ref\": \"#/definitions/Description\" },\n      \"completed\": { \"$ref\": \"#/definitions/Completed\" },\n      \"completedAt\": { \"$ref\": \"#/definitions/DateTime\" },\n      \"priority\": { \"$ref\": \"#/definitions/Priority\" },\n      \"taskListId\": { \"$ref\": \"#/definitions/DocID\" }\n    },\n    \"required\": [\"title\", \"completed\", \"priority\"],\n    \"additionalProperties\": false,\n    \"definitions\": {\n      \"Title\": { \"type\": \"string\", \"title\": \"Title\", \"minLength\": 1, \"maxLength\": 200 },\n      \"Description\": { \"type\": \"string\", \"title\": \"Description\", \"maxLength\": 5000 },\n      \"Completed\": { \"type\": \"boolean\", \"title\": \"Completed\", \"default\": false },\n      \"DateTime\": { \"type\": \"string\", \"format\": \"date-time\", \"title\": \"DateTime\" },\n      \"Priority\": {\n        \"type\": \"string\",\n        \"title\": \"Priority\",\n        \"enum\": [\"LOW\", \"MEDIUM\", \"HIGH\", \"URGENT\"],\n        \"default\": \"MEDIUM\"\n      },\n      \"DocID\": { \"type\": \"string\", \"title\": \"DocID\", \"pattern\": \"^k[0-9a-z]{10,120}$\" }\n    }\n  },\n  \"fieldsMeta\": {\n    \"taskListId\": { \"relationModel\": \"#5\" }\n  }\n}\n```\n\n**Note:** Concrete schemas use `\"additionalProperties\": false` to enforce strict structure.\n\n### Unique Constraint Model\n```json\n{\n  \"name\": \"UserProfile\",\n  \"version\": \"1.0\",\n  \"interfaces\": [],\n  \"behavior\": \"unique\",\n  \"uniqueFields\": [\"email\"],\n  \"schema\": {\n    \"type\": \"object\",\n    \"properties\": {\n      \"email\": { \"$ref\": \"#/definitions/Email\" },\n      \"displayName\": { \"$ref\": \"#/definitions/DisplayName\" }\n    },\n    \"required\": [\"email\"],\n    \"additionalProperties\": false,\n    \"definitions\": {\n      \"Email\": { \"type\": \"string\", \"format\": \"email\", \"title\": \"Email\" },\n      \"DisplayName\": { \"type\": \"string\", \"title\": \"DisplayName\", \"maxLength\": 100 }\n    }\n  },\n  \"fieldsMeta\": {}\n}\n```\n\n### Model with Any-Document Reference\n```json\n{\n  \"name\": \"Reminder\",\n  \"version\": \"1.0\",\n  \"interfaces\": [\"#0\"],\n  \"behavior\": \"default\",\n  \"schema\": {\n    \"type\": \"object\",\n    \"properties\": {\n      \"title\": { \"$ref\": \"#/definitions/Title\" },\n      \"linkedItemId\": { \"$ref\": \"#/definitions/DocID\" },\n      \"remindAt\": { \"$ref\": \"#/definitions/DateTime\" }\n    },\n    \"required\": [\"title\", \"remindAt\"],\n    \"additionalProperties\": false,\n    \"definitions\": {\n      \"Title\": { \"type\": \"string\", \"title\": \"Title\", \"minLength\": 1, \"maxLength\": 200 },\n      \"DocID\": { \"type\": \"string\", \"title\": \"DocID\", \"pattern\": \"^k[0-9a-z]{10,120}$\" },\n      \"DateTime\": { \"type\": \"string\", \"format\": \"date-time\", \"title\": \"DateTime\" }\n    }\n  },\n  \"fieldsMeta\": {\n    \"linkedItemId\": { \"relationModel\": null }\n  }\n}\n```\n\n---\n\n## Generation Guidelines\n\n1. **Never create a Node interface** - it's built-in and implicit\n2. **Never include \"Node\" in interfaces array** - all models inherit it automatically\n3. **Use `null` for any-document relations** - this represents the Node interface\n4. **Define interfaces first in clusters** - place them at lower indices (0, 1, 2...) so concrete models can reference them with `#N`\n5. **Ask clarifying questions** about requirements if needed\n6. **Choose appropriate behavior** (`default` / `interface` / `unique`)\n7. **Use predefined types** when they match the use case\n8. **Define clear field relationships** using `fieldsMeta`\n9. **Include reasonable validation** (lengths, patterns, ranges)\n10. **Follow naming conventions** strictly\n11. **Make required fields explicit**\n12. **Concrete models must include all interface fields** - copy the field definitions from implemented interfaces\n\n---\n\n## Cluster Organization\n\nWhen generating a model cluster, organize models in this order:\n\n1. **Interface models** (indices 0, 1, 2, ...) - Define abstract contracts first\n2. **Shared/referenced models** (e.g., Tag) - Models referenced by many others\n3. **Domain models** - Concrete models grouped by domain\n\n**Example cluster structure:**\n```\n#0  Schedulable (interface)\n#1  Completable (interface)\n#2  Prioritizable (interface)\n#3  Taggable (interface)\n#4  Tag (referenced by Taggable)\n#5  Event (implements #0, #3)\n#6  Task (implements #1, #2, #3)\n#7  Project (implements #1)\n```\n\n---\n\n## Response Format\n\nAlways generate models as a JSON array, even when a single model is needed. Validate that your output follows the specification exactly.";
+//# sourceMappingURL=data-model-designer.d.ts.map

package/lib/prompts/data-model-designer.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"data-model-designer.d.ts","sourceRoot":"","sources":["../../src/prompts/data-model-designer.ts"],"names":[],"mappings":"AAAA,eAAO,MAAM,yBAAyB,oyWAiWmG,CAAA"}

package/lib/prompts/data-model-designer.js

@@ -0,0 +1,354 @@
+export const KUBUN_PROMPT_INSTRUCTIONS = `# Kubun Protocol Data Model Generator
+
+You are an expert at creating data models following the Kubun protocol specification. Your task is to generate valid JSON schemas for data models based on user requirements.
+
+## Core Principles
+
+**Automatic Server Fields (DO NOT INCLUDE):**
+- \`id\` - Server generates globally unique DocID automatically
+- \`createdAt\` - Server generates timestamp automatically
+- \`updatedAt\` - Server generates timestamp automatically
+- Owner relations - Server handles user/owner associations automatically
+
+**Model Behaviors:**
+- \`default\` - Standard concrete models for real entities
+- \`interface\` - Abstract contracts that other models implement
+- \`unique\` - Models with uniqueness constraints on specific fields
+
+---
+
+## Built-in Interfaces
+
+### Node (Implicit Base Interface)
+
+**All models implicitly implement the \`Node\` interface.** This is the base interface for all documents in the system.
+
+- **DO NOT** create a \`Node\` interface model
+- **DO NOT** include \`"Node"\` in any model's \`interfaces\` array
+- **DO** use \`null\` as a \`relationModel\` value when a field can reference any document
+
+**Example - Field that can link to any document:**
+\`\`\`json
+{
+  "fieldsMeta": {
+    "linkedItemId": {
+      "relationModel": null
+    }
+  }
+}
+\`\`\`
+
+---
+
+## Schema Structure
+
+Each model must include:
+\`\`\`json
+{
+  "name": "PascalCaseModelName",
+  "version": "1.0",
+  "interfaces": [],
+  "schema": { /* JSON Schema definition */ },
+  "fieldsMeta": { /* DocID field metadata */ },
+  "behavior": "default|interface|unique",
+  "uniqueFields": ["field1", "field2"]
+}
+\`\`\`
+
+| Field | Required | Description |
+|-------|----------|-------------|
+| \`name\` | Yes | PascalCase model name |
+| \`version\` | Yes | Schema version (use \`"1.0"\`) |
+| \`interfaces\` | Yes | Array of interface references (see Interface References) |
+| \`schema\` | Yes | JSON Schema definition |
+| \`fieldsMeta\` | Yes | DocID field relationship metadata (can be empty \`{}\`) |
+| \`behavior\` | Yes | One of: \`default\`, \`interface\`, \`unique\` |
+| \`uniqueFields\` | Only for \`unique\` behavior | Array of field names that must be unique |
+
+---
+
+## Interface References
+
+The \`interfaces\` array specifies which interfaces a model implements. Reference format depends on where the interface is defined:
+
+| Interface Location | Reference Format | Example |
+|--------------------|------------------|---------|
+| Existing in database | Model ID | \`"k1a2b3c4d5e6f7g8h9"\` |
+| In same cluster being generated | Array index | \`"#0"\` |
+
+**Rules:**
+- All models implicitly implement \`Node\` - never include it in the interfaces array
+- When generating a new cluster, define interface models FIRST (at lower indices) so concrete models can reference them
+- Use \`#N\` format where N is the zero-based array index of the interface model in the cluster
+
+**Example - Model implementing cluster interfaces:**
+\`\`\`json
+{
+  "name": "Task",
+  "interfaces": ["#0", "#2"],
+  ...
+}
+\`\`\`
+
+---
+
+## Relations Between Models
+
+Use \`fieldsMeta\` to define DocID relationships:
+
+| Target Location | Reference Format | Description |
+|-----------------|------------------|-------------|
+| Any document (polymorphic to Node) | \`null\` | Field can link to any item in the system |
+| Existing in database | Model ID | \`"k1a2b3c4d5e6f7g8h9"\` |
+| In same cluster being generated | Array index | \`"#2"\` |
+
+**Example:**
+\`\`\`json
+{
+  "fieldsMeta": {
+    "taskListId": {
+      "relationModel": "#5"
+    },
+    "categoryId": {
+      "relationModel": "k1a2b3c4d5e6f7g8h9"
+    },
+    "linkedItemId": {
+      "relationModel": null
+    }
+  }
+}
+\`\`\`
+
+---
+
+## Naming Conventions
+
+| Element | Convention | Example |
+|---------|------------|---------|
+| Model names | PascalCase starting with uppercase | \`UserProfile\`, \`BlogPost\` |
+| Field names | camelCase starting with lowercase | \`firstName\`, \`createdDate\` |
+| Type titles | PascalCase | \`EmailAddress\`, \`PhoneNumber\` |
+| Enum values | UPPERCASE_UNDERSCORE | \`ACTIVE\`, \`PENDING_APPROVAL\` |
+
+---
+
+## Available Data Types
+
+### Predefined Types (Use When Applicable)
+
+When a predefined type matches your use case, copy its exact definition into the \`definitions\` section and reference it. Never create custom types that duplicate predefined functionality.
+
+| Type | Purpose |
+|------|---------|
+| \`AttachmentID\` | File/media references |
+| \`BigInt\` | Large integers |
+| \`DateTime\` | ISO 8601 date-time |
+| \`DID\` | Decentralized identifiers |
+| \`DocID\` | Document references |
+| \`Duration\` | ISO 8601 duration |
+| \`JSONObject\` | Flexible JSON data |
+| \`Latitude\` / \`Longitude\` | Geographic coordinates |
+| \`LocalDate\` | Date without time (YYYY-MM-DD) |
+| \`LocalDateTime\` | Local date-time |
+| \`LocalTime\` | Time without date |
+| \`Locale\` | Language/region codes |
+| \`TimeZone\` | Timezone identifiers |
+| \`URL\` | Web addresses |
+| \`UtcOffset\` | UTC time offsets |
+
+**Usage Pattern:**
+\`\`\`json
+{
+  "properties": {
+    "scheduledAt": { "$ref": "#/definitions/DateTime" }
+  },
+  "definitions": {
+    "DateTime": { "type": "string", "format": "date-time", "title": "DateTime" }
+  }
+}
+\`\`\`
+
+### Primitive Types
+
+| Type | Variants |
+|------|----------|
+| \`boolean\` | True/false values |
+| \`integer\` | Whole numbers (with optional min/max) |
+| \`number\` | Decimal numbers (with optional min/max) |
+| \`string\` | Plain text, \`const\`, \`pattern\`, \`enum\`, \`format\` |
+
+### Complex Types
+
+| Type | Description |
+|------|-------------|
+| \`array\` | Collections of items |
+| \`object\` | Structured data with properties |
+
+---
+
+## Example Patterns
+
+### Interface Model
+\`\`\`json
+{
+  "name": "Completable",
+  "version": "1.0",
+  "interfaces": [],
+  "behavior": "interface",
+  "schema": {
+    "type": "object",
+    "properties": {
+      "completed": { "$ref": "#/definitions/Completed" },
+      "completedAt": { "$ref": "#/definitions/DateTime" }
+    },
+    "required": ["completed"],
+    "additionalProperties": true,
+    "definitions": {
+      "Completed": { "type": "boolean", "title": "Completed", "default": false },
+      "DateTime": { "type": "string", "format": "date-time", "title": "DateTime" }
+    }
+  },
+  "fieldsMeta": {}
+}
+\`\`\`
+
+**Note:** Interface schemas use \`"additionalProperties": true\` to allow implementing models to add fields.
+
+### Concrete Model (Implementing Interfaces)
+\`\`\`json
+{
+  "name": "Task",
+  "version": "1.0",
+  "interfaces": ["#0", "#1"],
+  "behavior": "default",
+  "schema": {
+    "type": "object",
+    "properties": {
+      "title": { "$ref": "#/definitions/Title" },
+      "description": { "$ref": "#/definitions/Description" },
+      "completed": { "$ref": "#/definitions/Completed" },
+      "completedAt": { "$ref": "#/definitions/DateTime" },
+      "priority": { "$ref": "#/definitions/Priority" },
+      "taskListId": { "$ref": "#/definitions/DocID" }
+    },
+    "required": ["title", "completed", "priority"],
+    "additionalProperties": false,
+    "definitions": {
+      "Title": { "type": "string", "title": "Title", "minLength": 1, "maxLength": 200 },
+      "Description": { "type": "string", "title": "Description", "maxLength": 5000 },
+      "Completed": { "type": "boolean", "title": "Completed", "default": false },
+      "DateTime": { "type": "string", "format": "date-time", "title": "DateTime" },
+      "Priority": {
+        "type": "string",
+        "title": "Priority",
+        "enum": ["LOW", "MEDIUM", "HIGH", "URGENT"],
+        "default": "MEDIUM"
+      },
+      "DocID": { "type": "string", "title": "DocID", "pattern": "^k[0-9a-z]{10,120}$" }
+    }
+  },
+  "fieldsMeta": {
+    "taskListId": { "relationModel": "#5" }
+  }
+}
+\`\`\`
+
+**Note:** Concrete schemas use \`"additionalProperties": false\` to enforce strict structure.
+
+### Unique Constraint Model
+\`\`\`json
+{
+  "name": "UserProfile",
+  "version": "1.0",
+  "interfaces": [],
+  "behavior": "unique",
+  "uniqueFields": ["email"],
+  "schema": {
+    "type": "object",
+    "properties": {
+      "email": { "$ref": "#/definitions/Email" },
+      "displayName": { "$ref": "#/definitions/DisplayName" }
+    },
+    "required": ["email"],
+    "additionalProperties": false,
+    "definitions": {
+      "Email": { "type": "string", "format": "email", "title": "Email" },
+      "DisplayName": { "type": "string", "title": "DisplayName", "maxLength": 100 }
+    }
+  },
+  "fieldsMeta": {}
+}
+\`\`\`
+
+### Model with Any-Document Reference
+\`\`\`json
+{
+  "name": "Reminder",
+  "version": "1.0",
+  "interfaces": ["#0"],
+  "behavior": "default",
+  "schema": {
+    "type": "object",
+    "properties": {
+      "title": { "$ref": "#/definitions/Title" },
+      "linkedItemId": { "$ref": "#/definitions/DocID" },
+      "remindAt": { "$ref": "#/definitions/DateTime" }
+    },
+    "required": ["title", "remindAt"],
+    "additionalProperties": false,
+    "definitions": {
+      "Title": { "type": "string", "title": "Title", "minLength": 1, "maxLength": 200 },
+      "DocID": { "type": "string", "title": "DocID", "pattern": "^k[0-9a-z]{10,120}$" },
+      "DateTime": { "type": "string", "format": "date-time", "title": "DateTime" }
+    }
+  },
+  "fieldsMeta": {
+    "linkedItemId": { "relationModel": null }
+  }
+}
+\`\`\`
+
+---
+
+## Generation Guidelines
+
+1. **Never create a Node interface** - it's built-in and implicit
+2. **Never include "Node" in interfaces array** - all models inherit it automatically
+3. **Use \`null\` for any-document relations** - this represents the Node interface
+4. **Define interfaces first in clusters** - place them at lower indices (0, 1, 2...) so concrete models can reference them with \`#N\`
+5. **Ask clarifying questions** about requirements if needed
+6. **Choose appropriate behavior** (\`default\` / \`interface\` / \`unique\`)
+7. **Use predefined types** when they match the use case
+8. **Define clear field relationships** using \`fieldsMeta\`
+9. **Include reasonable validation** (lengths, patterns, ranges)
+10. **Follow naming conventions** strictly
+11. **Make required fields explicit**
+12. **Concrete models must include all interface fields** - copy the field definitions from implemented interfaces
+
+---
+
+## Cluster Organization
+
+When generating a model cluster, organize models in this order:
+
+1. **Interface models** (indices 0, 1, 2, ...) - Define abstract contracts first
+2. **Shared/referenced models** (e.g., Tag) - Models referenced by many others
+3. **Domain models** - Concrete models grouped by domain
+
+**Example cluster structure:**
+\`\`\`
+#0  Schedulable (interface)
+#1  Completable (interface)
+#2  Prioritizable (interface)
+#3  Taggable (interface)
+#4  Tag (referenced by Taggable)
+#5  Event (implements #0, #3)
+#6  Task (implements #1, #2, #3)
+#7  Project (implements #1)
+\`\`\`
+
+---
+
+## Response Format
+
+Always generate models as a JSON array, even when a single model is needed. Validate that your output follows the specification exactly.`;

package/lib/prompts/index.d.ts

@@ -0,0 +1,15 @@
+export declare const prompts: {
+    'data-model-designer': {
+        description: string;
+        handler: () => {
+            messages: {
+                role: "user";
+                content: {
+                    type: "text";
+                    text: string;
+                };
+            }[];
+        };
+    };
+};
+//# sourceMappingURL=index.d.ts.map

package/lib/prompts/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/prompts/index.ts"],"names":[],"mappings":"AAEA,eAAO,MAAM,OAAO;;;;;;;;;;;;;CAenB,CAAA"}

package/lib/prompts/index.js

@@ -0,0 +1,19 @@
+import { KUBUN_PROMPT_INSTRUCTIONS } from './data-model-designer.js';
+export const prompts = {
+    'data-model-designer': {
+        description: 'Instructions to help design a data model following the Kubun protocol specification',
+        handler: ()=>{
+            return {
+                messages: [
+                    {
+                        role: 'user',
+                        content: {
+                            type: 'text',
+                            text: KUBUN_PROMPT_INSTRUCTIONS
+                        }
+                    }
+                ]
+            };
+        }
+    }
+};

package/lib/run.d.ts

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

package/lib/run.d.ts.map

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

package/lib/run.js

@@ -0,0 +1,19 @@
+#!/usr/bin/env node
+import { parseArgs } from 'node:util';
+import { serveProcess } from '@mokei/context-server';
+import { createConfig } from './config.js';
+const args = parseArgs({
+    options: {
+        connect: {
+            type: 'string'
+        },
+        db: {
+            type: 'string'
+        }
+    }
+});
+const config = createConfig({
+    connect: args.values.connect,
+    database: args.values.db
+});
+serveProcess(config);

package/lib/tools/cluster.d.ts

@@ -0,0 +1,6 @@
+import type { KubunClient } from '@kubun/client';
+import { createTool } from '@mokei/context-server';
+type ToolDefinition = ReturnType<typeof createTool>;
+export declare function createClusterTools(client: KubunClient): Record<string, ToolDefinition>;
+export {};
+//# sourceMappingURL=cluster.d.ts.map

package/lib/tools/cluster.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"cluster.d.ts","sourceRoot":"","sources":["../../src/tools/cluster.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,eAAe,CAAA;AAEhD,OAAO,EAAE,UAAU,EAAe,MAAM,uBAAuB,CAAA;AAE/D,KAAK,cAAc,GAAG,UAAU,CAAC,OAAO,UAAU,CAAC,CAAA;AAEnD,wBAAgB,kBAAkB,CAAC,MAAM,EAAE,WAAW,GAAG,MAAM,CAAC,MAAM,EAAE,cAAc,CAAC,CA8CtF"}

package/lib/tools/cluster.js

@@ -0,0 +1,71 @@
+import { ClusterBuilder, clusterModel } from '@kubun/protocol';
+import { createTool } from '@mokei/context-server';
+export function createClusterTools(client) {
+    const create_cluster = createTool('Create a new cluster from model definitions', {
+        type: 'object',
+        properties: {
+            models: {
+                type: 'array',
+                items: {
+                    type: 'object'
+                }
+            }
+        },
+        required: [
+            'models'
+        ],
+        additionalProperties: false
+    }, async (ctx)=>{
+        const builder = new ClusterBuilder();
+        builder.addAll(ctx.arguments.models);
+        const cluster = builder.build();
+        return {
+            content: [
+                {
+                    type: 'text',
+                    text: 'Cluster created'
+                }
+            ],
+            structuredContent: {
+                cluster
+            }
+        };
+    });
+    const deploy_clusters = createTool('Deploy clusters to the Kubun backend', {
+        type: 'object',
+        properties: {
+            clusters: {
+                type: 'array',
+                items: clusterModel
+            },
+            id: {
+                type: 'string'
+            }
+        },
+        required: [
+            'clusters'
+        ],
+        additionalProperties: false
+    }, async (ctx)=>{
+        const result = await client.deployGraph({
+            id: ctx.arguments.id,
+            clusters: ctx.arguments.clusters
+        });
+        return {
+            content: [
+                {
+                    type: 'text',
+                    text: `Clusters deployed to graph "${result.id}"`
+                }
+            ],
+            structuredContent: {
+                id: result.id,
+                models: result.models
+            }
+        };
+    });
+    return {
+        create_cluster,
+        deploy_clusters
+    };
+}

package/lib/tools/graph.d.ts

@@ -0,0 +1,6 @@
+import type { KubunClient } from '@kubun/client';
+import { createTool } from '@mokei/context-server';
+type ToolDefinition = ReturnType<typeof createTool>;
+export declare function createGraphTools(client: KubunClient): Record<string, ToolDefinition>;
+export {};
+//# sourceMappingURL=graph.d.ts.map

package/lib/tools/graph.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"graph.d.ts","sourceRoot":"","sources":["../../src/tools/graph.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,eAAe,CAAA;AAKhD,OAAO,EAAE,UAAU,EAAe,MAAM,uBAAuB,CAAA;AAG/D,KAAK,cAAc,GAAG,UAAU,CAAC,OAAO,UAAU,CAAC,CAAA;AA2BnD,wBAAgB,gBAAgB,CAAC,MAAM,EAAE,WAAW,GAAG,MAAM,CAAC,MAAM,EAAE,cAAc,CAAC,CAuKpF"}

package/lib/tools/graph.js

@@ -0,0 +1,248 @@
+import { createSchema } from '@kubun/graphql';
+import { createTool } from '@mokei/context-server';
+import { printSchema } from 'graphql';
+function getModelsInfo(result) {
+    if (result.models == null) {
+        return {};
+    }
+    const aliases = result.aliases ?? {};
+    return Object.entries(result.models).reduce((acc, [id, model])=>{
+        const alias = aliases[id] ?? model.name;
+        acc[alias] = {
+            id,
+            behavior: model.behavior,
+            interfaces: model.interfaces,
+            fields: Object.keys(model.schema.properties)
+        };
+        return acc;
+    }, {});
+}
+export function createGraphTools(client) {
+    const graph_list = createTool('List all available graphs', {}, async ()=>{
+        const result = await client.listGraphs();
+        const graphs = result.graphs.map((graph)=>`${graph.name} (${graph.id})`).join(', ');
+        return {
+            content: [
+                {
+                    type: 'text',
+                    text: graphs === '' ? 'No graphs available' : `Available graphs: ${graphs}`
+                }
+            ],
+            structuredContent: {
+                graphs: result.graphs
+            }
+        };
+    });
+    const graph_info = createTool('Get information about a specific graph', {
+        type: 'object',
+        properties: {
+            id: {
+                type: 'string'
+            }
+        },
+        required: [
+            'id'
+        ],
+        additionalProperties: false
+    }, async (ctx)=>{
+        try {
+            const result = await client.loadGraph({
+                id: ctx.arguments.id
+            });
+            if (result.models == null) {
+                throw new Error(`Models not found for graph: ${ctx.arguments.id}`);
+            }
+            const info = getModelsInfo(result);
+            return {
+                content: [
+                    {
+                        type: 'text',
+                        text: JSON.stringify(info)
+                    }
+                ],
+                structuredContent: info
+            };
+        } catch (error) {
+            return {
+                isError: true,
+                content: [
+                    {
+                        type: 'text',
+                        text: `Failed to get GraphQL schema: ${error instanceof Error ? error.message : String(error)}`
+                    }
+                ]
+            };
+        }
+    });
+    const graph_schema = createTool('Get the GraphQL schema for the given graph ID', {
+        type: 'object',
+        properties: {
+            id: {
+                type: 'string'
+            }
+        },
+        required: [
+            'id'
+        ],
+        additionalProperties: false
+    }, async (ctx)=>{
+        try {
+            const result = await client.loadGraph({
+                id: ctx.arguments.id
+            });
+            if (result.models == null) {
+                throw new Error(`Models not found for graph: ${ctx.arguments.id}`);
+            }
+            const schema = createSchema(result.models, result.aliases);
+            return {
+                content: [
+                    {
+                        type: 'text',
+                        text: printSchema(schema)
+                    }
+                ]
+            };
+        } catch (error) {
+            return {
+                isError: true,
+                content: [
+                    {
+                        type: 'text',
+                        text: `Failed to get GraphQL schema: ${error instanceof Error ? error.message : String(error)}`
+                    }
+                ]
+            };
+        }
+    });
+    const graph_query = createTool('Execute a GraphQL query on the given graph ID', {
+        type: 'object',
+        properties: {
+            id: {
+                type: 'string'
+            },
+            query: {
+                type: 'string'
+            },
+            variables: {
+                type: 'object'
+            }
+        },
+        required: [
+            'id',
+            'query'
+        ],
+        additionalProperties: false
+    }, async (ctx)=>{
+        try {
+            const result = await client.queryGraph({
+                id: ctx.arguments.id,
+                text: ctx.arguments.query,
+                variables: ctx.arguments.variables ?? {}
+            });
+            if (result.errors != null && result.errors.length > 0) {
+                return {
+                    isError: true,
+                    content: [
+                        {
+                            type: 'text',
+                            text: result.errors.map((e)=>e.toString()).join(', ')
+                        }
+                    ],
+                    structuredContent: {
+                        errors: result.errors
+                    }
+                };
+            }
+            return {
+                content: [
+                    {
+                        type: 'text',
+                        text: JSON.stringify(result.data)
+                    }
+                ],
+                structuredContent: {
+                    data: result.data
+                }
+            };
+        } catch (error) {
+            return {
+                isError: true,
+                content: [
+                    {
+                        type: 'text',
+                        text: `Failed to execute GraphQL query: ${error instanceof Error ? error.message : String(error)}`
+                    }
+                ]
+            };
+        }
+    });
+    const graph_mutate = createTool('Execute a GraphQL mutation on the given graph ID', {
+        type: 'object',
+        properties: {
+            id: {
+                type: 'string'
+            },
+            query: {
+                type: 'string'
+            },
+            variables: {
+                type: 'object'
+            }
+        },
+        required: [
+            'id',
+            'query'
+        ],
+        additionalProperties: false
+    }, async (ctx)=>{
+        try {
+            const result = await client.mutateGraph({
+                id: ctx.arguments.id,
+                text: ctx.arguments.query,
+                variables: ctx.arguments.variables ?? {}
+            });
+            if (result.errors != null && result.errors.length > 0) {
+                return {
+                    isError: true,
+                    content: [
+                        {
+                            type: 'text',
+                            text: result.errors.map((e)=>e.toString()).join(', ')
+                        }
+                    ],
+                    structuredContent: {
+                        errors: result.errors
+                    }
+                };
+            }
+            return {
+                content: [
+                    {
+                        type: 'text',
+                        text: JSON.stringify(result.data)
+                    }
+                ],
+                structuredContent: {
+                    data: result.data
+                }
+            };
+        } catch (error) {
+            return {
+                isError: true,
+                content: [
+                    {
+                        type: 'text',
+                        text: `Failed to execute GraphQL mutation: ${error instanceof Error ? error.message : String(error)}`
+                    }
+                ]
+            };
+        }
+    });
+    return {
+        graph_list,
+        graph_info,
+        graph_schema,
+        graph_query,
+        graph_mutate
+    };
+}

package/lib/tools/index.d.ts

@@ -0,0 +1,3 @@
+export { createClusterTools } from './cluster.js';
+export { createGraphTools } from './graph.js';
+//# sourceMappingURL=index.d.ts.map

package/lib/tools/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/tools/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,kBAAkB,EAAE,MAAM,cAAc,CAAA;AACjD,OAAO,EAAE,gBAAgB,EAAE,MAAM,YAAY,CAAA"}

package/lib/tools/index.js

@@ -0,0 +1,2 @@
+export { createClusterTools } from './cluster.js';
+export { createGraphTools } from './graph.js';

package/package.json

@@ -0,0 +1,47 @@
+{
+  "name": "@kubun/mcp",
+  "version": "0.1.0",
+  "description": "MCP server for Kubun",
+  "keywords": [],
+  "type": "module",
+  "main": "lib/index.js",
+  "types": "lib/index.d.ts",
+  "exports": {
+    ".": "./lib/index.js",
+    "./run": "./lib/run.js"
+  },
+  "bin": {
+    "kubun-mcp": "./lib/run.js"
+  },
+  "files": [
+    "lib/*"
+  ],
+  "sideEffects": false,
+  "dependencies": {
+    "@enkaku/token": "0.12.3",
+    "@mokei/context-server": "^0.4.0",
+    "graphql": "^16.12.0",
+    "@kubun/db": "^0.4.0",
+    "@kubun/db-postgres": "^0.4.0",
+    "@kubun/db-sqlite": "^0.4.0",
+    "@kubun/http-client": "^0.4.0",
+    "@kubun/protocol": "^0.4.0",
+    "@kubun/graphql": "^0.4.2",
+    "@kubun/server": "^0.4.1"
+  },
+  "devDependencies": {
+    "@enkaku/transport": "0.12.0",
+    "@mokei/context-client": "^0.4.0",
+    "@mokei/context-protocol": "^0.4.0",
+    "@kubun/client": "^0.4.0"
+  },
+  "scripts": {
+    "build:clean": "del lib",
+    "build:js": "swc src -d ./lib --config-file ../../swc.json --strip-leading-paths",
+    "build:types": "tsc --emitDeclarationOnly --skipLibCheck",
+    "build": "pnpm run build:clean && pnpm run build:js && pnpm run build:types",
+    "test:types": "tsc --noEmit",
+    "test:unit": "vitest run",
+    "test": "pnpm run test:types && pnpm run test:unit"
+  }
+}