regen-koi-mcp 1.0.4 → 1.0.5

package/README.md

@@ -114,12 +114,26 @@ This MCP server gives AI assistants access to Regen Network's comprehensive know
 
 ## 📦 Available Tools
 
+### Knowledge Base Search
 | Tool | Description | Key Inputs |
 |------|-------------|-----------|
 | `search_knowledge` | Hybrid search (vectors + graph with RRF) | `query` (string), `limit` (1–20, default 5), `published_from` (YYYY‑MM‑DD), `published_to` (YYYY‑MM‑DD), `include_undated` (bool, default false) |
+| `hybrid_search` | Intelligent search routing (auto-detects entity vs conceptual queries) | `query` (string), `limit` (1–50, default 10) |
 | `get_stats` | Knowledge base statistics | `detailed` (boolean) |
 | `generate_weekly_digest` | Generate weekly digest of Regen Network activity | `start_date` (YYYY-MM-DD, default: 7 days ago), `end_date` (YYYY-MM-DD, default: today), `save_to_file` (bool, default false), `output_path` (string), `format` ('markdown' or 'json', default: 'markdown') |
 
+### Code Knowledge Graph
+| Tool | Description | Key Inputs |
+|------|-------------|-----------|
+| `query_code_graph` | Query relationships between Keepers, Messages, Events, and Documentation | `query_type` (enum: keeper_for_msg, msgs_for_keeper, docs_mentioning, entities_in_doc, related_entities), `entity_name` (string), `doc_path` (string) |
+
+### GitHub Documentation
+| Tool | Description | Key Inputs |
+|------|-------------|-----------|
+| `search_github_docs` | Search Regen GitHub repos for documentation and technical content | `query` (string), `repository` (optional: regen-ledger, regen-web, regen-data-standards, regenie-corpus), `limit` (1-20, default 10) |
+| `get_repo_overview` | Get structured overview of a Regen repository | `repository` (enum: regen-ledger, regen-web, regen-data-standards, regenie-corpus) |
+| `get_tech_stack` | Get technical stack information for Regen repositories | `repository` (optional, omit to show all repos) |
+
 ## 🏗️ Architecture
 
 This repo contains everything you need to run a complete KOI MCP setup:
@@ -588,6 +602,43 @@ Built by the Regen Network community to make ecological knowledge accessible to
 
 ---
 
+## 🛠️ Developer & Deployment Documentation
+
+For developers and operators who want to run their own instance or contribute:
+
+| Document | Description |
+|----------|-------------|
+| [docs/INFRASTRUCTURE.md](docs/INFRASTRUCTURE.md) | Server requirements, PostgreSQL setup, Apache AGE installation |
+| [docs/DEPLOYMENT.md](docs/DEPLOYMENT.md) | Production deployment guide, systemd setup, monitoring |
+| [docs/TECHNICAL_ASSISTANT_PROJECT.md](docs/TECHNICAL_ASSISTANT_PROJECT.md) | Full project tracking and implementation details |
+| [ARCHITECTURE.md](ARCHITECTURE.md) | System architecture and component overview |
+
+### Quick Local Development with Docker
+
+Spin up a complete development stack with PostgreSQL + pgvector + Apache AGE:
+
+```bash
+cd docker/
+docker-compose up -d
+```
+
+This starts everything needed for full functionality including graph queries.
+
+### Deploy Scripts
+
+```bash
+# Install Apache AGE on existing PostgreSQL
+./scripts/deploy/install-apache-age.sh
+
+# Setup database schema and extensions
+./scripts/deploy/setup-database.sh
+
+# Load graph data (entities, summaries, relationships)
+./scripts/deploy/load-graph-data.sh
+```
+
+---
+
 ## 🏗️ Related Repositories
 
 This MCP client is part of the larger KOI ecosystem:

package/dist/graph_client.d.ts

@@ -0,0 +1,204 @@
+/**
+ * Graph Client - Apache AGE Query Abstraction Layer
+ *
+ * Provides a clean interface for querying the Regen code knowledge graph
+ * stored in PostgreSQL with Apache AGE extension.
+ */
+interface GraphClientConfig {
+    host: string;
+    port: number;
+    database: string;
+    user?: string;
+    password?: string;
+    graphName: string;
+}
+export interface Keeper {
+    name: string;
+    file_path: string;
+    line_number: number;
+    docstring?: string;
+    fields?: string[];
+}
+export interface Msg {
+    name: string;
+    file_path: string;
+    line_number: number;
+    docstring?: string;
+    fields?: string[];
+    package?: string;
+}
+export interface Document {
+    title: string;
+    file_path: string;
+    rid?: string;
+    content?: string;
+}
+export interface Entity {
+    type: string;
+    name: string;
+    file_path?: string;
+    line_number?: number;
+    docstring?: string;
+}
+export interface RelatedEntity {
+    name: string;
+    type: string;
+    shared_docs?: number;
+}
+export interface Module {
+    name: string;
+    repo: string;
+    path: string;
+    summary?: string;
+    entity_count: number;
+}
+export interface ModuleSearchResult {
+    name: string;
+    repo: string;
+    path: string;
+    summary?: string;
+    entity_count: number;
+    score?: number;
+}
+export interface ModuleEntity {
+    type: string;
+    name: string;
+    file_path?: string;
+    line_number?: number;
+}
+export interface KeeperForMsgResult {
+    keeper_name: string;
+    keeper_file_path: string;
+    keeper_line_number: number;
+}
+export interface MsgForKeeperResult {
+    msg_name: string;
+    msg_package?: string;
+}
+export interface DocMentioningResult {
+    file_path: string;
+    title: string;
+}
+export interface EntityInDocResult {
+    type: string;
+    name: string;
+}
+/**
+ * GraphClient - Interface for querying the code knowledge graph
+ */
+export declare class GraphClient {
+    private pool;
+    private graphName;
+    constructor(config: GraphClientConfig);
+    /**
+     * Close the database connection pool
+     */
+    close(): Promise<void>;
+    /**
+     * Execute a raw Cypher query
+     */
+    private executeCypher;
+    /**
+     * Query 1: Find which Keeper handles a given Msg
+     */
+    getKeeperForMsg(msgName: string): Promise<KeeperForMsgResult[]>;
+    /**
+     * Query 2: List all Msgs a Keeper handles
+     */
+    getMsgsForKeeper(keeperName: string): Promise<MsgForKeeperResult[]>;
+    /**
+     * Query 3: Find documents that mention an entity
+     */
+    getDocsMentioning(entityName: string): Promise<DocMentioningResult[]>;
+    /**
+     * Query 4: Find all entities mentioned in a document
+     */
+    getEntitiesInDoc(docPath: string): Promise<EntityInDocResult[]>;
+    /**
+     * Query 5: Find entities related to a given entity (via shared docs or direct edges)
+     */
+    getRelatedEntities(entityName: string): Promise<RelatedEntity[]>;
+    /**
+     * Get graph statistics
+     */
+    getStats(): Promise<{
+        node_counts: Record<string, number>;
+        edge_counts: Record<string, number>;
+    }>;
+    /**
+     * Search for entities by name pattern
+     */
+    searchEntities(pattern: string, entityType?: string): Promise<Entity[]>;
+    /**
+     * Get all Keepers
+     */
+    getAllKeepers(): Promise<Keeper[]>;
+    /**
+     * Get all Msgs
+     */
+    getAllMsgs(): Promise<Msg[]>;
+    /**
+     * Get entities by repository name
+     */
+    getEntitiesByRepo(repoName: string, limit?: number): Promise<Entity[]>;
+    /**
+     * Get entities by type (Sensor, Handler, Class, Interface, Function, etc.)
+     */
+    getEntitiesByType(typeName: string, limit?: number): Promise<Entity[]>;
+    /**
+     * Search entities by name (case-insensitive contains)
+     */
+    findEntitiesByName(searchTerm: string, limit?: number): Promise<Entity[]>;
+    /**
+     * Get all repositories with entity counts
+     */
+    getRepositories(): Promise<Array<{
+        name: string;
+        entity_count: number;
+    }>>;
+    /**
+     * Get entity type distribution for a repository
+     */
+    getRepoEntityTypes(repoName: string): Promise<Array<{
+        type: string;
+        count: number;
+    }>>;
+    /**
+     * Get all modules with their summaries
+     */
+    getAllModules(limit?: number): Promise<Module[]>;
+    /**
+     * Get a specific module by name
+     */
+    getModule(moduleName: string, repo?: string): Promise<Module | null>;
+    /**
+     * Search modules by name pattern (case-insensitive)
+     */
+    searchModules(pattern: string, limit?: number): Promise<ModuleSearchResult[]>;
+    /**
+     * Get all entities contained in a module
+     */
+    getModuleEntities(moduleName: string, repo?: string, limit?: number): Promise<ModuleEntity[]>;
+    /**
+     * Get modules by repository
+     */
+    getModulesByRepo(repoName: string, limit?: number): Promise<Module[]>;
+    /**
+     * Find which module contains a given entity
+     */
+    getModuleForEntity(entityName: string): Promise<Module | null>;
+    /**
+     * Get module statistics (count by repo)
+     */
+    getModuleStats(): Promise<Array<{
+        repo: string;
+        module_count: number;
+        total_entities: number;
+    }>>;
+}
+/**
+ * Create a default GraphClient instance using environment variables
+ */
+export declare function createGraphClient(): GraphClient;
+export {};
+//# sourceMappingURL=graph_client.d.ts.map

package/dist/graph_client.d.ts.map

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

package/dist/graph_client.js

@@ -0,0 +1,360 @@
+/**
+ * Graph Client - Apache AGE Query Abstraction Layer
+ *
+ * Provides a clean interface for querying the Regen code knowledge graph
+ * stored in PostgreSQL with Apache AGE extension.
+ */
+import pkg from 'pg';
+const { Pool } = pkg;
+/**
+ * GraphClient - Interface for querying the code knowledge graph
+ */
+export class GraphClient {
+    pool;
+    graphName;
+    constructor(config) {
+        this.graphName = config.graphName;
+        this.pool = new Pool({
+            host: config.host,
+            port: config.port,
+            database: config.database,
+            user: config.user,
+            password: config.password,
+        });
+    }
+    /**
+     * Close the database connection pool
+     */
+    async close() {
+        await this.pool.end();
+    }
+    /**
+     * Execute a raw Cypher query
+     */
+    async executeCypher(query, params = []) {
+        const client = await this.pool.connect();
+        try {
+            // Load AGE extension for this session
+            await client.query("LOAD 'age';");
+            await client.query(`SET search_path = ag_catalog, "$user", public;`);
+            // Apache AGE requires wrapping the cypher() call with column definitions
+            // We use a generic 'result agtype' column and parse the results
+            const cypherQuery = `SELECT * FROM ag_catalog.cypher('${this.graphName}', $$ ${query} $$) as (result agtype)`;
+            const result = await client.query(cypherQuery, params);
+            // AGE returns results wrapped in agtype format
+            return result.rows.map((row) => {
+                const agtypeValue = row.result;
+                // Parse the agtype value - it can be a vertex, edge, or primitive
+                if (agtypeValue === null || agtypeValue === undefined) {
+                    return null;
+                }
+                // AGE returns agtype as objects that need to be parsed
+                let parsed;
+                if (typeof agtypeValue === 'string') {
+                    // String-encoded JSON
+                    try {
+                        parsed = JSON.parse(agtypeValue);
+                    }
+                    catch {
+                        parsed = agtypeValue;
+                    }
+                }
+                else if (typeof agtypeValue === 'object') {
+                    // Already an object - might be a vertex/edge or a map
+                    if (agtypeValue.properties) {
+                        // This is a vertex or edge - extract properties
+                        parsed = agtypeValue.properties;
+                    }
+                    else {
+                        // This is a plain object/map
+                        parsed = agtypeValue;
+                    }
+                }
+                else {
+                    // Primitive value
+                    parsed = agtypeValue;
+                }
+                return parsed;
+            }).filter((item) => item !== null);
+        }
+        finally {
+            client.release();
+        }
+    }
+    /**
+     * Query 1: Find which Keeper handles a given Msg
+     */
+    async getKeeperForMsg(msgName) {
+        const query = `
+      MATCH (k:Keeper)-[:HANDLES]->(m:Msg {name: '${msgName}'})
+      RETURN {keeper_name: k.name, keeper_file_path: k.file_path, keeper_line_number: k.line_number}
+    `;
+        return this.executeCypher(query);
+    }
+    /**
+     * Query 2: List all Msgs a Keeper handles
+     */
+    async getMsgsForKeeper(keeperName) {
+        const query = `
+      MATCH (k:Keeper {name: '${keeperName}'})-[:HANDLES]->(m:Msg)
+      RETURN {msg_name: m.name, msg_package: m.package}
+    `;
+        return this.executeCypher(query);
+    }
+    /**
+     * Query 3: Find documents that mention an entity
+     */
+    async getDocsMentioning(entityName) {
+        const query = `
+      MATCH (d:Document)-[:MENTIONS]->(e {name: '${entityName}'})
+      RETURN {file_path: d.file_path, title: d.title}
+    `;
+        return this.executeCypher(query);
+    }
+    /**
+     * Query 4: Find all entities mentioned in a document
+     */
+    async getEntitiesInDoc(docPath) {
+        const query = `
+      MATCH (d:Document {file_path: '${docPath}'})-[:MENTIONS]->(e)
+      RETURN {type: labels(e)[0], name: e.name}
+    `;
+        return this.executeCypher(query);
+    }
+    /**
+     * Query 5: Find entities related to a given entity (via shared docs or direct edges)
+     */
+    async getRelatedEntities(entityName) {
+        const query = `
+      MATCH (e1 {name: '${entityName}'})<-[:MENTIONS]-(d:Document)-[:MENTIONS]->(e2)
+      WHERE e1 <> e2
+      WITH DISTINCT e2, count(d) as shared_docs
+      RETURN {name: e2.name, type: labels(e2)[0], shared_docs: shared_docs}
+      ORDER BY shared_docs DESC
+    `;
+        return this.executeCypher(query);
+    }
+    /**
+     * Get graph statistics
+     */
+    async getStats() {
+        // Count nodes by label
+        const nodeQuery = `
+      MATCH (n)
+      WITH labels(n)[0] as label, count(*) as count
+      RETURN {label: label, count: count}
+    `;
+        const nodeResults = await this.executeCypher(nodeQuery);
+        // Count edges by type
+        const edgeQuery = `
+      MATCH ()-[r]->()
+      WITH type(r) as type, count(*) as count
+      RETURN {type: type, count: count}
+    `;
+        const edgeResults = await this.executeCypher(edgeQuery);
+        const node_counts = {};
+        nodeResults.forEach(r => {
+            node_counts[r.label] = r.count;
+        });
+        const edge_counts = {};
+        edgeResults.forEach(r => {
+            edge_counts[r.type] = r.count;
+        });
+        return { node_counts, edge_counts };
+    }
+    /**
+     * Search for entities by name pattern
+     */
+    async searchEntities(pattern, entityType) {
+        const typeFilter = entityType ? `labels(e)[0] = '${entityType}' AND` : '';
+        const query = `
+      MATCH (e)
+      WHERE ${typeFilter} e.name =~ '.*${pattern}.*'
+      RETURN {type: labels(e)[0], name: e.name, file_path: e.file_path, line_number: e.line_number, docstring: e.docstring}
+      LIMIT 50
+    `;
+        return this.executeCypher(query);
+    }
+    /**
+     * Get all Keepers
+     */
+    async getAllKeepers() {
+        const query = `
+      MATCH (k:Keeper)
+      RETURN {name: k.name, file_path: k.file_path, line_number: k.line_number, docstring: k.docstring, fields: k.fields}
+    `;
+        return this.executeCypher(query);
+    }
+    /**
+     * Get all Msgs
+     */
+    async getAllMsgs() {
+        const query = `
+      MATCH (m:Msg)
+      RETURN {name: m.name, file_path: m.file_path, line_number: m.line_number, docstring: m.docstring, fields: m.fields, package: m.package}
+    `;
+        return this.executeCypher(query);
+    }
+    // ============= Multi-Language Entity Queries =============
+    /**
+     * Get entities by repository name
+     */
+    async getEntitiesByRepo(repoName, limit = 50) {
+        const query = `
+      MATCH (r:Repository {name: '${repoName}'})-[:CONTAINS]->(e)
+      RETURN {type: labels(e)[0], name: e.name, file_path: e.file_path, line_number: e.line_number, docstring: e.docstring}
+      LIMIT ${limit}
+    `;
+        return this.executeCypher(query);
+    }
+    /**
+     * Get entities by type (Sensor, Handler, Class, Interface, Function, etc.)
+     */
+    async getEntitiesByType(typeName, limit = 50) {
+        const query = `
+      MATCH (e:${typeName})
+      RETURN {type: labels(e)[0], name: e.name, file_path: e.file_path, line_number: e.line_number, docstring: e.docstring}
+      LIMIT ${limit}
+    `;
+        return this.executeCypher(query);
+    }
+    /**
+     * Search entities by name (case-insensitive contains)
+     */
+    async findEntitiesByName(searchTerm, limit = 20) {
+        // Use toLower for case-insensitive matching
+        const query = `
+      MATCH (e)
+      WHERE toLower(e.name) CONTAINS toLower('${searchTerm}')
+      RETURN {type: labels(e)[0], name: e.name, file_path: e.file_path, line_number: e.line_number, docstring: e.docstring, repo: e.repo, language: e.language}
+      ORDER BY e.name
+      LIMIT ${limit}
+    `;
+        return this.executeCypher(query);
+    }
+    /**
+     * Get all repositories with entity counts
+     */
+    async getRepositories() {
+        const query = `
+      MATCH (r:Repository)-[:CONTAINS]->(e)
+      WITH r.name as name, count(e) as entity_count
+      RETURN {name: name, entity_count: entity_count}
+    `;
+        return this.executeCypher(query);
+    }
+    /**
+     * Get entity type distribution for a repository
+     */
+    async getRepoEntityTypes(repoName) {
+        const query = `
+      MATCH (r:Repository {name: '${repoName}'})-[:CONTAINS]->(e)
+      WITH labels(e)[0] as type, count(*) as count
+      RETURN {type: type, count: count}
+      ORDER BY count DESC
+    `;
+        return this.executeCypher(query);
+    }
+    // ============= RAPTOR Module Queries =============
+    /**
+     * Get all modules with their summaries
+     */
+    async getAllModules(limit = 50) {
+        const query = `
+      MATCH (m:Module)
+      RETURN {name: m.name, repo: m.repo, path: m.path, summary: m.summary, entity_count: m.entity_count}
+      ORDER BY m.entity_count DESC
+      LIMIT ${limit}
+    `;
+        return this.executeCypher(query);
+    }
+    /**
+     * Get a specific module by name
+     */
+    async getModule(moduleName, repo) {
+        const repoFilter = repo ? `repo: '${repo}',` : '';
+        const query = `
+      MATCH (m:Module {${repoFilter} name: '${moduleName}'})
+      RETURN {name: m.name, repo: m.repo, path: m.path, summary: m.summary, entity_count: m.entity_count}
+      LIMIT 1
+    `;
+        const results = await this.executeCypher(query);
+        return results.length > 0 ? results[0] : null;
+    }
+    /**
+     * Search modules by name pattern (case-insensitive)
+     */
+    async searchModules(pattern, limit = 10) {
+        const query = `
+      MATCH (m:Module)
+      WHERE toLower(m.name) CONTAINS toLower('${pattern}')
+         OR toLower(m.summary) CONTAINS toLower('${pattern}')
+      RETURN {name: m.name, repo: m.repo, path: m.path, summary: m.summary, entity_count: m.entity_count}
+      ORDER BY m.entity_count DESC
+      LIMIT ${limit}
+    `;
+        return this.executeCypher(query);
+    }
+    /**
+     * Get all entities contained in a module
+     */
+    async getModuleEntities(moduleName, repo, limit = 50) {
+        const repoFilter = repo ? `repo: '${repo}',` : '';
+        const query = `
+      MATCH (m:Module {${repoFilter} name: '${moduleName}'})-[:CONTAINS]->(e)
+      RETURN {type: labels(e)[0], name: e.name, file_path: e.file_path, line_number: e.line_number}
+      LIMIT ${limit}
+    `;
+        return this.executeCypher(query);
+    }
+    /**
+     * Get modules by repository
+     */
+    async getModulesByRepo(repoName, limit = 20) {
+        const query = `
+      MATCH (m:Module {repo: '${repoName}'})
+      RETURN {name: m.name, repo: m.repo, path: m.path, summary: m.summary, entity_count: m.entity_count}
+      ORDER BY m.entity_count DESC
+      LIMIT ${limit}
+    `;
+        return this.executeCypher(query);
+    }
+    /**
+     * Find which module contains a given entity
+     */
+    async getModuleForEntity(entityName) {
+        const query = `
+      MATCH (m:Module)-[:CONTAINS]->(e {name: '${entityName}'})
+      RETURN {name: m.name, repo: m.repo, path: m.path, summary: m.summary, entity_count: m.entity_count}
+      LIMIT 1
+    `;
+        const results = await this.executeCypher(query);
+        return results.length > 0 ? results[0] : null;
+    }
+    /**
+     * Get module statistics (count by repo)
+     */
+    async getModuleStats() {
+        const query = `
+      MATCH (m:Module)
+      WITH m.repo as repo, count(m) as module_count, sum(m.entity_count) as total_entities
+      RETURN {repo: repo, module_count: module_count, total_entities: total_entities}
+      ORDER BY total_entities DESC
+    `;
+        return this.executeCypher(query);
+    }
+}
+/**
+ * Create a default GraphClient instance using environment variables
+ */
+export function createGraphClient() {
+    return new GraphClient({
+        host: process.env.GRAPH_DB_HOST || 'localhost',
+        port: parseInt(process.env.GRAPH_DB_PORT || '5432'),
+        database: process.env.GRAPH_DB_NAME || 'eliza',
+        user: process.env.GRAPH_DB_USER,
+        password: process.env.GRAPH_DB_PASSWORD,
+        graphName: process.env.GRAPH_NAME || 'regen_graph',
+    });
+}
+//# sourceMappingURL=graph_client.js.map

package/dist/graph_client.js.map

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