🌱 Regen KOI MCP Server

Access Regen Network's Knowledge Organization Infrastructure (KOI) through Model Context Protocol (MCP) tools in Claude Desktop, VSCode, and other MCP-compatible clients.

🚀 Quick Start

Choose your installation method:

• Native CLI commands (Recommended) - Most transparent and secure
• Automated install script - Convenient for multiple clients at once
• Manual configuration - Full control over your setup

Recommended: Native CLI Commands

The simplest and most secure way to install for supported clients:

Claude Code CLI:

claude mcp add regen-koi npx regen-koi-mcp@latest

Codex: (requires manual config - see Codex section for full instructions)

# CLI adds the server, but you must manually add startup_timeout_sec = 30
codex mcp add regen-koi npx "-y regen-koi-mcp@latest"

Warp:

/add-mcp regen-koi npx -y regen-koi-mcp@latest

Amp:

amp mcp add regen-koi -- npx -y regen-koi-mcp@latest

Factory:

droid mcp add regen-koi "npx -y regen-koi-mcp@latest"

Then configure the environment variable (see client-specific sections below for details).

Alternative: Automated Install Script

⚠️ Security Note: This script requires bash access and modifies config files. Review the install script before running.

curl -fsSL https://raw.githubusercontent.com/gaiaaiagent/regen-koi-mcp/main/install.sh | bash

What this does:

• Automatically configures Claude Desktop and Claude Code CLI
• Sets up environment variables
• Works for multiple clients at once

Quick Test: After installation, restart your client and ask: "What repositories are indexed in KOI?" to verify the tools are working.

Manual Configuration (All Clients)

For clients without a CLI command, manually add this configuration:

{
  "mcpServers": {
    "regen-koi": {
      "command": "npx",
      "args": ["regen-koi-mcp@latest"],
      "env": {
        "KOI_API_ENDPOINT": "https://regen.gaiaai.xyz/api/koi"
      }
    }
  }
}

Benefits:

• ✅ Automatic updates - get new features without doing anything
• ✅ No git clone, no build, no maintenance
• ✅ Always uses the latest version
• ✅ Works immediately

Config file locations:

• Mac: ~/Library/Application Support/Claude/claude_desktop_config.json
• Windows: %APPDATA%\Claude\claude_desktop_config.json
• Linux: ~/.config/Claude/claude_desktop_config.json

Then restart Claude Desktop and you're done! 🎉

Quick Test: Ask Claude: "What repositories are indexed in KOI?" to verify the tools are working.

For existing git users: See the migration section below for a simple one-line script to switch to npx.

🔄 Migrating from Git Installation

If you previously installed via git clone, switch to npx for automatic updates.

⚠️ Security Note: Review the migrate script before running.

curl -fsSL https://raw.githubusercontent.com/gaiaaiagent/regen-koi-mcp/main/migrate.sh | bash

What this does:

• ✅ Backs up your existing config
• ✅ Updates command: "node" → command: "npx"
• ✅ Updates args to use regen-koi-mcp@latest
• ✅ Configures Claude Code CLI too
• ✅ You get automatic updates forever!

After migration, you can safely delete your old git clone directory.

Option 2: Local Development (Git Clone)

For contributors or local development only:

git clone https://github.com/gaiaaiagent/regen-koi-mcp
cd regen-koi-mcp
npm install
npm run build

Then manually configure your MCP client to point to the local dist/index.js.

Requirements:

• Node.js 16+: Download here
• Python 3.8+: Download here - Optional (only for advanced local digest generation)

🏠 Deployment Options

🌐 Option 1: Hosted API (Default - Recommended)

By default, the MCP client connects to the hosted KOI API at https://regen.gaiaai.xyz/api/koi. This works out of the box - no additional setup required!

🖥️ Option 2: Self-Hosted API Server

Want to run your own API server with direct database access? See ARCHITECTURE.md for setup instructions.

🏗️ Option 3: Full Self-Hosted Pipeline

Want complete control including data collection? You'll need:

• This repo (MCP client + API server)
• koi-sensors - Data collection from Discourse, Ledger, etc.
• koi-processor - Batch processing pipeline

See ARCHITECTURE.md for detailed setup instructions and architecture overview.

🔐 Authentication (Optional - Team Members Only)

Public Data (No Auth Required)

KOI provides access to extensive public Regen Network knowledge:

• ✅ Regen Ledger code and documentation
• ✅ Regen Network forum discussions
• ✅ Public GitHub repositories
• ✅ Website content and blogs

Most users don't need authentication - just install and start querying!

Internal Documentation (Regen Network Team)

Regen Network team members with @regen.network emails can optionally authenticate to access additional internal documentation.

To authenticate:

User: "Please use the regen_koi_authenticate tool"

MCP: ## Authentication Required

     🌐 Your browser should open automatically. If not, click:
     [Open Activation Page](https://regen.gaiaai.xyz/activate)

     Enter this code: NWDV-FCFC

     Sign in with your @regen.network email.

     After completing, run this tool again to retrieve your session token.

User: [Completes authentication in browser]
      "Please use the regen_koi_authenticate tool again"

MCP: ✅ Authentication Successful!
     You now have access to internal Regen Network documentation.

     Authenticated as: yourname@regen.network

After authentication:

• Queries automatically include internal documentation
• Token is saved locally in ~/.koi-auth.json and cached in memory
• Session expires after ~1 hour
• Browser auto-opens to activation page for convenience

What Permissions Are Requested

The OAuth flow requests minimal, identity-only permissions:

• ✅ openid - Verify your identity
• ✅ email - Confirm you're @regen.network
• ✅ profile - Basic profile info

NOT requested:

• ❌ Access to your personal Drive files
• ❌ Access to your Gmail
• ❌ Any write/modification permissions

The service account (not your OAuth token) handles all data access.

Example: Team Member Workflow

# First time - authenticate
User: "Use regen_koi_authenticate to authenticate me"

MCP: Opening browser...
     ✅ Authenticated as: alice@regen.network

# Now all queries include internal docs
User: "How do I register a carbon project?"

MCP: Found 23 results from multiple sources:
     - Project Registration Guide (2024)
     - Registry Standards Documentation
     - Carbon Methodology Overview
     ...

Token Security

Your authentication tokens are:

• 🔒 Local Storage: Saved in ~/.koi-auth.json with 0o600 permissions (owner read/write only)
• 🔒 Database: SHA-256 hashed when stored in PostgreSQL (no plain tokens stored)
• 🔒 User-Specific: Never shared between users; each session is isolated
• 🔒 Short-Lived: Sessions expire after 1 hour; tokens are revocable
• 🔒 Domain Enforcement: Only @regen.network emails are permitted (verified in JWT claims)
• 🔒 Phishing Prevention: RFC 8628 Device Authorization Grant with user-typed codes
• 🔒 Rate Limited: 5 attempts/min on activation, 60 req/min on token endpoint
• 🔒 No Secrets in URLs: All authentication flows use POST requests to prevent logging
• 🔒 Hardcoded URLs: Activation page URL is hardcoded in the client (not from server)
• 🔒 JWT Validation: Google ID tokens validated locally with signature verification

Production-Ready: This authentication system follows RFC 8628 and industry best practices.

See docs/AUTHENTICATION.md for complete security documentation and threat model.

Troubleshooting

"Authentication window opened but nothing happened"

• Check if your browser blocked the popup
• Try manually clicking the URL shown in the terminal

"Access denied" after logging in

• Ensure you're using your @regen.network email (not personal Gmail)
• Contact your Workspace admin if you don't have access

Still having issues?

• Open an issue: https://github.com/gaiaaiagent/regen-koi-mcp/issues

🎯 What This Does

This MCP server gives AI assistants access to Regen Network's comprehensive knowledge base with 15,000+ documents about:

• Carbon credits and ecological assets
• Regenerative agriculture practices
• Blockchain and Web3 sustainability
• Climate action and environmental data
• Regen Registry credit classes

Note: This MCP server connects to our hosted KOI API at https://regen.gaiaai.xyz/api/koi (behind HTTPS via Nginx), so you don't need to run any infrastructure locally.

🎓 Quick Start: Example Queries

Once you've installed the MCP server, try these queries in Claude to explore what's available:

🔍 Discovery: What's Indexed?

"What repositories are indexed in the KOI knowledge base?"
"What types of code entities exist?"
"Show me statistics about what's in the knowledge base"

What you'll get: The system has indexed 5 repositories (regen-ledger, regen-web, koi-sensors, and more) with 26,768 code entities including Methods, Functions, Structs, and Interfaces.

💻 Code Exploration: Find Specific Code

"Search for functions containing 'keeper' in regen-ledger"
"Find all code related to MsgCreateBatch"
"What Structs exist in the ecocredit module?"
"Show me all Interface types in regen-ledger"
"Search for retirement-related code"

What you'll get: Direct links to code entities with file paths and signatures. The graph contains Methods, Functions, Structs, and Interfaces extracted via tree-sitter AST parsing.

📚 Documentation: Understanding the System

"Explain the ecocredit module architecture"
"What's the tech stack for regen-web?"
"Search GitHub docs for information about credit classes"
"Get an overview of the regen-ledger repository"

What you'll get: Architectural explanations, technology choices, and relevant documentation from GitHub repositories.

🔬 Advanced: Graph Traversal

"What functions call CreateBatch?"
"What does the NewKeeper function call?"
"Find orphaned code that's never called"
"Show me the call graph for MsgRetire"

What you'll get: Call graph traversal showing function relationships (CALLS edges), orphan detection, and code dependency analysis.

📊 Knowledge Base: Recent Activity

"Generate a weekly digest of Regen Network discussions"
"Search for recent discussions about carbon credits from the past week"
"Find documentation about basket creation from 2024"

What you'll get: Summaries of community discussions, forum posts, and activity with source citations.

🔎 Source Filtering & Date Sorting

"Get the latest 5 documents from the Notion database"
"Show me recent Discourse forum posts sorted by date"
"Search GitHub for ecocredit documentation"
"Find the newest content from any source"

What you'll get: Documents filtered by source (notion, github, discourse, youtube, podcast, web, gitlab) and sorted chronologically. Available sources can be discovered via get_stats.

📦 Available Tools

Knowledge Base Search

Code Knowledge Graph

SPARQL Power Tools (Advanced)

GitHub Documentation

Authentication (Team Members Only)

🤔 What Can I Ask? User Guide

This table helps you understand which tool to use for different tasks. Just ask Claude in natural language - it will automatically use the right tool.

Query Type Reference

The query_code_graph tool supports these query types:

Discovery

• list_repos - Show all indexed repositories with entity counts
• list_entity_types - Show all entity types (Function, Class, Keeper, Message, etc.) with counts
• get_entity_stats - Comprehensive statistics: entities by type, language, repository
• list_keepers - List all Keeper entities with pagination (supports limit and offset)
• list_messages - List all Message entities with pagination (supports limit and offset)
• list_modules - Show all modules across repositories

Entity Queries

• find_by_type - Find all entities of a specific type (requires entity_type parameter)
• search_entities - Search entities by name pattern (requires entity_name parameter)
• related_entities - Find entities related to a given entity (requires entity_name parameter)

Relationship Queries

• keeper_for_msg - Find which Keeper handles a Message (requires entity_name parameter)
• msgs_for_keeper - Find what Messages a Keeper handles (requires entity_name parameter)
• docs_mentioning - Find documentation mentioning an entity (requires entity_name parameter)
• entities_in_doc - Find entities defined in a document (requires doc_path parameter)

Module Queries

• get_module - Get details about a specific module (requires module_name parameter)
• search_modules - Search modules by keyword (requires entity_name parameter)
• module_entities - Get entities in a module (requires module_name parameter)
• module_for_entity - Find which module contains an entity (requires entity_name parameter)

When to Use Which Tool

Rule of thumb:

• Use query_code_graph for common queries (keepers, messages, relationships)
• Use resolve_entity / get_entity_neighborhood for entity lookups
• Use sparql_query for complex queries not covered by other tools

SPARQL Query Examples

The sparql_query tool executes raw SPARQL against the Apache Jena knowledge graph. Common prefixes are auto-added if not specified.

Example 1: Simple SELECT - Find all Organizations

SELECT ?org ?label WHERE {
  ?org a schema:Organization .
  OPTIONAL { ?org rdfs:label ?label }
}

Example 2: Relationship Lookup - Find statements about a topic

SELECT ?stmt ?predicate ?object WHERE {
  ?stmt regen:subject ?subject .
  ?stmt regen:predicate ?predicate .
  ?stmt regen:object ?object .
  FILTER(CONTAINS(LCASE(STR(?subject)), "carbon credit"))
}

Example 3: Find All Messages/Keepers with Relationships

SELECT ?keeper ?msg ?msgName WHERE {
  ?keeper a <Keeper> .
  ?keeper <HANDLES> ?msg .
  ?msg rdfs:label ?msgName .
}
ORDER BY ?keeper

Safety Features

The sparql_query tool enforces several safety measures:

• Max query length: 5,000 characters
• Result row cap: 1,000 rows (configurable via limit parameter)
• Timeout: Default 30s, max 60s
• Read-only: Only SELECT queries allowed (no DELETE, INSERT, DROP)
• Privacy: Raw queries are never logged; only query hash + summary are recorded

What's Currently Indexed

Repositories: 5 total

• regen-ledger: 18,619 entities (Go, Cosmos SDK modules)
• regen-web: 3,164 entities (TypeScript/React frontend)
• koi-sensors: 1,250 entities (Python data collection)
• regen-koi-mcp: 688 entities (TypeScript MCP server)
• regen-data-standards: 6 entities (JSON schemas)

Entity Types: 10 types

• Function, Class, Interface, Method, Type
• Keeper, Message, Query, Event (Cosmos SDK specific)
• Module, Repository

Total: 23,728 code entities

🏗️ Architecture

This repo contains everything you need to run a complete KOI MCP setup:

regen-koi-mcp/
├── src/              # MCP client (connects to API)
├── server/           # KOI API server (FastAPI)
│   ├── src/          # API endpoints
│   ├── setup.sh      # Server setup
│   ├── start.sh      # Start server
│   └── stop.sh       # Stop server
└── python/           # Weekly digest generator
    ├── src/          # Digest logic
    ├── config/       # Configuration
    └── setup.sh      # Python setup

Two modes:

1. Client-only (default): MCP client → Hosted API
2. Self-hosted: MCP client → Your local API → Your database

💻 Supported Clients

Claude Desktop

Recommended: Manual configuration

Add to your config file:

• Mac: ~/Library/Application Support/Claude/claude_desktop_config.json
• Windows: %APPDATA%\Claude\claude_desktop_config.json
• Linux: ~/.config/Claude/claude_desktop_config.json

{
  "mcpServers": {
    "regen-koi": {
      "command": "npx",
      "args": ["regen-koi-mcp@latest"],
      "env": {
        "KOI_API_ENDPOINT": "https://regen.gaiaai.xyz/api/koi"
      }
    }
  }
}

Alternative: Automated installer

⚠️ Security Note: Review the install script before running.

curl -fsSL https://raw.githubusercontent.com/gaiaaiagent/regen-koi-mcp/main/install.sh | bash

Claude Code CLI

Recommended: One-line command

claude mcp add regen-koi npx regen-koi-mcp@latest

Then manually add the environment variable to your Claude Code settings file:

Mac/Linux: ~/.config/claude/claude_code_config.json Windows: %APPDATA%\claude\claude_code_config.json

{
  "mcpServers": {
    "regen-koi": {
      "command": "npx",
      "args": ["regen-koi-mcp@latest"],
      "env": {
        "KOI_API_ENDPOINT": "https://regen.gaiaai.xyz/api/koi"
      }
    }
  }
}

Alternative: Use the automated installer

⚠️ Security Note: Review the install script before running.

curl -fsSL https://raw.githubusercontent.com/gaiaaiagent/regen-koi-mcp/main/install.sh | bash

This configures both Claude Desktop and Claude Code CLI with the correct environment variables.

Verification: After installation, restart Claude Code and ask: "What repositories are indexed?" to verify the tools are working.

VS Code / VS Code Insiders

Recommended: CLI command

For VS Code:

code --add-mcp '{"name":"regen-koi","command":"npx","args":["regen-koi-mcp@latest"],"env":{"KOI_API_ENDPOINT":"https://regen.gaiaai.xyz/api/koi"}}'

For VS Code Insiders:

code-insiders --add-mcp '{"name":"regen-koi","command":"npx","args":["regen-koi-mcp@latest"],"env":{"KOI_API_ENDPOINT":"https://regen.gaiaai.xyz/api/koi"}}'

Alternative: Manual configuration

Add to your VS Code MCP settings with the command, args, and env values shown above.

Cursor

Via Settings:

1. Open Cursor Settings
2. Go to MCP section
3. Click "Add new MCP Server"
4. Enter:
   • Name: regen-koi
   • Command: npx
   • Args: regen-koi-mcp@latest
   • Env: KOI_API_ENDPOINT=https://regen.gaiaai.xyz/api/koi

Windsurf

Add to your Windsurf MCP config:

{
  "mcpServers": {
    "regen-koi": {
      "command": "npx",
      "args": ["regen-koi-mcp@latest"],
      "env": {
        "KOI_API_ENDPOINT": "https://regen.gaiaai.xyz/api/koi"
      }
    }
  }
}

Cline (VS Code Extension)

Install Cline from VS Code Marketplace, then add to Cline's MCP settings:

{
  "mcpServers": {
    "regen-koi": {
      "command": "npx",
      "args": ["regen-koi-mcp@latest"],
      "env": {
        "KOI_API_ENDPOINT": "https://regen.gaiaai.xyz/api/koi"
      }
    }
  }
}

Continue (VS Code Extension)

Install Continue from VS Code Marketplace, then add to Continue's config:

{
  "mcpServers": {
    "regen-koi": {
      "command": "npx",
      "args": ["regen-koi-mcp@latest"],
      "env": {
        "KOI_API_ENDPOINT": "https://regen.gaiaai.xyz/api/koi"
      }
    }
  }
}

Goose

Via Settings:

1. Open Advanced settings
2. Go to Extensions
3. Add MCP server with:
   • Command: npx
   • Args: regen-koi-mcp@latest
   • Env: KOI_API_ENDPOINT=https://regen.gaiaai.xyz/api/koi

Warp

Recommended: Slash command

/add-mcp regen-koi npx -y regen-koi-mcp@latest

Then add the environment variable KOI_API_ENDPOINT=https://regen.gaiaai.xyz/api/koi in the server settings.

Alternative: Manual configuration via Settings

1. Open Settings → AI → Manage MCP Servers
2. Add new server
3. Configure:
   • Command: npx
   • Args: regen-koi-mcp@latest
   • Env: KOI_API_ENDPOINT=https://regen.gaiaai.xyz/api/koi

Amp

Recommended: One-line command

amp mcp add regen-koi -- npx -y regen-koi-mcp@latest

Then manually add the environment variable KOI_API_ENDPOINT=https://regen.gaiaai.xyz/api/koi to the server configuration.

Factory

Recommended: One-line command

droid mcp add regen-koi "npx -y regen-koi-mcp@latest"

Then manually add the environment variable KOI_API_ENDPOINT=https://regen.gaiaai.xyz/api/koi to the server configuration.

Alternative: Interactive UI

Use the /mcp command in Factory to add the server interactively.

Codex

Recommended: Manual configuration

Edit ~/.codex/config.toml directly:

[[mcp.servers]]
name = "regen-koi"
command = "npx"
args = ["-y", "regen-koi-mcp@latest"]
startup_timeout_sec = 30
[mcp.servers.env]
KOI_API_ENDPOINT = "https://regen.gaiaai.xyz/api/koi"

Note: The startup_timeout_sec = 30 is required because the MCP server takes longer than Codex's default 10-second timeout to initialize (especially on first run when npx downloads the package).

Alternative: CLI command + manual edit

codex mcp add regen-koi npx "-y regen-koi-mcp@latest"

Then edit ~/.codex/config.toml to add startup_timeout_sec = 30 under the [mcp_servers.regen-koi] section.

Opencode

Add to ~/.config/opencode/opencode.json:

{
  "mcpServers": {
    "regen-koi": {
      "command": "npx",
      "args": ["regen-koi-mcp@latest"],
      "env": {
        "KOI_API_ENDPOINT": "https://regen.gaiaai.xyz/api/koi"
      }
    }
  }
}

Kiro

Add to .kiro/settings/mcp.json:

{
  "mcpServers": {
    "regen-koi": {
      "command": "npx",
      "args": ["regen-koi-mcp@latest"],
      "env": {
        "KOI_API_ENDPOINT": "https://regen.gaiaai.xyz/api/koi"
      }
    }
  }
}

LM Studio

Via Settings:

1. Open Program sidebar
2. Go to MCP configuration
3. Add server with npx command: npx regen-koi-mcp@latest

Qodo Gen (VS Code / IntelliJ)

Via Chat Panel:

1. Open Qodo Gen chat
2. Click "Connect more tools"
3. Add MCP server:
   • Command: npx
   • Args: regen-koi-mcp@latest
   • Env: KOI_API_ENDPOINT=https://regen.gaiaai.xyz/api/koi

Gemini CLI

Add to Gemini CLI MCP config:

{
  "mcpServers": {
    "regen-koi": {
      "command": "npx",
      "args": ["regen-koi-mcp@latest"],
      "env": {
        "KOI_API_ENDPOINT": "https://regen.gaiaai.xyz/api/koi"
      }
    }
  }
}

Other MCP-Compatible Clients

Any MCP-compatible client can use this server with:

{
  "command": "npx",
  "args": ["regen-koi-mcp@latest"],
  "env": {
    "KOI_API_ENDPOINT": "https://regen.gaiaai.xyz/api/koi"
  }
}

🌍 Environment Configuration

Create a .env file in the project root:

# Required: KOI API endpoint
KOI_API_ENDPOINT=https://regen.gaiaai.xyz/api/koi

# Optional: API key if your KOI server requires authentication
# KOI_API_KEY=your_api_key_here

# Graph + NL→SPARQL configuration (used internally by hybrid search)
JENA_ENDPOINT=http://localhost:3030/koi/sparql
CONSOLIDATION_PATH=/opt/projects/koi-processor/src/core/final_consolidation_all_t0.25.json
PATTERNS_PATH=/opt/projects/koi-processor/src/core/predicate_patterns.json
COMMUNITY_PATH=/opt/projects/koi-processor/src/core/predicate_communities.json
EMBEDDING_SERVICE_URL=http://localhost:8095
# OPENAI_API_KEY=your_key  # Optional; template queries used when absent

🏗️ Development

# Run in development mode
npm run dev

# Build TypeScript
npm run build

# Clean build files
npm run clean

🔎 How Hybrid Graph Search Works

• Adaptive dual‑branch execution (internally via MCP):
  • Focused: top‑K predicates via embeddings + usage + community expansion
  • Broad: entity/topic regex over all predicates
  • Canonical‑aware filtering (keywords → regx:canonicalPredicate) by default
  • Smart fallback: if canonical returns 0 results, retry broad without canonical to recover recall
• Results fused with Reciprocal Rank Fusion (RRF) for precision + recall
• Date filter support: when published_from/published_to are provided, the vector and keyword branches are filtered server‑side. If include_undated is true, undated docs are also included. The graph branch adds a date filter only when RDF statements include regx:publishedAt (optional enrichment).
• Natural‑language recency detection: phrases like “past week”, “last month”, “last 30 days”, “yesterday”, “today” automatically set a date range when no explicit published_from/published_to are provided.

Examples

Direct KOI API examples (useful for testing filters):

# Natural-language recency ("past week") — MCP parses this automatically,
# but you can also hit the KOI API directly for verification
curl -s http://localhost:8301/api/koi/query \
  -H 'Content-Type: application/json' \
  -d '{
    "question": "what discussions about token design happened in the past week?",
    "limit": 10
  }' | jq '.results[0:3]'

# Explicit date range with include_undated=true
curl -s http://localhost:8301/api/koi/query \
  -H 'Content-Type: application/json' \
  -d '{
    "question": "token design",
    "limit": 10,
    "filters": {
      "date_range": { "start": "2025-10-09", "end": "2025-10-16" },
      "include_undated": true
    }
  }' | jq '.results[0:3]'

Within MCP, the search tool accepts:

• published_from / published_to (YYYY-MM-DD)
• include_undated (boolean) If you omit dates but include phrases like “past week”, the MCP infers the date range automatically.

📊 Evaluation

Run the built‑in harness and inspect results:

node scripts/eval-nl2sparql.js

• Persists JSON to results/eval_*.json with focused/broad sizes, union/overlap, latency, noise rate.
• Current baseline: 100% queries answered, 0% noise, ~1.5 s average latency.

📋 Prerequisites

• Node.js 18 or higher
• Claude Desktop or compatible MCP client
• Internet connection (connects to hosted KOI API)

🛠️ Troubleshooting

"KOI API not accessible"

The setup connects to our hosted KOI API at https://regen.gaiaai.xyz/api/koi. If you see connection errors, check your internet connection or firewall settings.

"Tools not showing in Claude"

1. Restart Claude Desktop after configuration
2. Check the config file syntax is valid JSON
3. Ensure the path to index.js is absolute

"Command not found"

Make sure Node.js is installed and in your PATH. The setup script uses node command.

"Connection error: localhost:8301" or "localhost:8910"

Cause: Claude caches MCP configurations in ~/.claude.json. If you previously ran a local dev server, it may have cached localhost URLs that override your current config.

Fix:

# 1. Check for cached localhost configs
grep -i "localhost.*8301\|localhost.*8910" ~/.claude.json

# 2. Backup your config
cp ~/.claude.json ~/.claude.json.backup

# 3. Replace localhost with public API
sed -i '' 's|http://localhost:8301/api/koi|https://regen.gaiaai.xyz/api/koi|g' ~/.claude.json
sed -i '' 's|http://localhost:8910/api/koi|https://regen.gaiaai.xyz/api/koi|g' ~/.claude.json

# 4. Restart Claude Code/Desktop

Prevention: Always use https://regen.gaiaai.xyz/api/koi in MCP configs unless you're actively developing the API server locally.

📚 Example Usage

Once configured, you can ask Claude:

• "Search the KOI knowledge base for information about carbon credits"
• "Get statistics about the knowledge base"
• "List active Regen Registry credit classes"
• "Find recent activity on the Regen Network"
• "Generate a weekly digest of Regen Network activity from the past week"
• "Create a digest of discussions from January 1 to January 7, 2025"

Weekly Digest Tools

There are two tools for getting weekly activity information, each designed for different use cases:

generate_weekly_digest - Curated Summary

Creates a condensed, curated markdown summary of Regen Network activity. Best for quick overview and reading in Claude.

Features:

• Executive summary with key highlights
• Curated selection of important discussions and updates
• Governance analysis and community insights
• On-chain metrics summary
• Automatically aggregates content from the past 7 days (or custom date range)

Examples:

"Generate a weekly digest of Regen Network activity"
"Create a digest from December 1 to December 8, 2024"
"Generate a weekly digest and save it to weekly_summary.md"

get_notebooklm_export - Full Content Export

Returns the complete, unabridged source material. Best for deep analysis or loading into NotebookLM.

Features:

• Full forum thread posts - Complete text of all posts, not just summaries
• Complete Notion page content - All chunks combined into full documents
• Enriched URLs - Metadata and context for linked resources
• Detailed source material - Everything you need for thorough analysis
• Generates on demand if no recent cached version exists (takes 2-3 minutes)

Examples:

"Get the full NotebookLM export"
"Get the complete weekly content with all forum posts"
"Export the full source material and save it to notebooklm_export.md"

When to use which:

• Use generate_weekly_digest for a quick, readable summary
• Use get_notebooklm_export when you need raw source content for deep analysis, fact-checking, or loading into external tools like NotebookLM

🤝 Contributing

Contributions welcome! Please feel free to submit issues and pull requests.

📄 License

MIT License - see LICENSE file for details

🔗 Links

• GitHub Repository
• Regen Network
• Model Context Protocol
• Claude Desktop

🌟 Credits

Built by the Regen Network community to make ecological knowledge accessible to AI assistants everywhere.

🛠️ Developer & Deployment Documentation

For developers and operators who want to run their own instance or contribute:

Quick Local Development with Docker

Spin up a complete development stack with PostgreSQL + pgvector + Apache AGE:

cd docker/
docker-compose up -d

This starts everything needed for full functionality including graph queries.

Deploy Scripts

# 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:

• koi-sensors - Real-time data collection from Discourse, Regen Ledger, websites, etc.
• koi-processor - Batch processing pipeline for chunking, embedding, and graph construction

See ARCHITECTURE.md for how these components work together.