MCP 服务器

OpenCode LLM Wiki MCP Server

Enables AI agents to interact with a persistent knowledge graph backend using MCP tools for reading, searching, and analyzing wiki pages with vector search and graph algorithms.

README

OpenCode LLM Wiki

Knowledge Graph Backend with Vector Search & Graph Algorithms HTTP API • CLI Tools • MCP Protocol • Vector Search • Knowledge Graph • Graph Analytics

<a href="#what-is-this">What is this?</a> • <a href="#architecture">Architecture</a> • <a href="#features">Features</a> • <a href="#installation">Installation</a> • <a href="#quick-start">Quick Start</a> • <a href="#license">License</a>

English | <a href="README_ZH.md">中文</a>

What is this?

OpenCode LLM Wiki is a knowledge graph backend that provides persistent, queryable knowledge storage with multiple access interfaces. It maintains a structured wiki with vector search and graph algorithms, accessible via HTTP API, CLI tools, or AI agents through the Model Context Protocol (MCP).

Core Philosophy

Persistent Knowledge Engine for AI Agents and Developers

This is a knowledge graph backend that provides multiple access methods for storing, indexing, and retrieving structured knowledge. Unlike ephemeral RAG systems that forget everything after each conversation, this project provides:

Persistent Wiki Storage: Markdown files in .wiki/pages/ with metadata-driven indexing
Multiple Interfaces: HTTP API, CLI tools, and MCP protocol for different use cases
Knowledge Graph: Automatic link extraction and relationship mapping with graph algorithms
Vector Search: RuVector-powered semantic search with 2048-dimensional embeddings
Cross-Session Memory: Knowledge persists across sessions, conversations, and tools
Graph Algorithms: PageRank, community detection, shortest paths, centrality analysis

Use Cases

AI Agent Memory: Persistent context that survives across conversations (via MCP)
Codebase Documentation: Living architecture docs queryable through API or CLI
Project Knowledge Base: Store decisions, patterns, and tribal knowledge
Research Notes: Organize papers, articles, and findings with semantic search
Personal Wiki: Build a second brain accessible through multiple interfaces

Architecture

Three-Layer Knowledge Engine

┌─────────────────────────────────────────────────────────────┐
│ Layer 1: Interface Layer (Multiple Access Points)           │
│  ┌──────────────┐  ┌──────────────┐  ┌──────────────┐     │
│  │  HTTP API    │  │     CLI      │  │  MCP Server  │     │
│  │  (Axum)      │  │   (clap)     │  │  (Node.js)   │     │
│  │  Port 19828  │  │              │  │  stdio       │     │
│  └──────────────┘  └──────────────┘  └──────────────┘     │
│  • Request validation and routing                          │
│  • Response formatting                                     │
│  • No business logic                                       │
└─────────────────────────────────────────────────────────────┘
                            ↓
┌─────────────────────────────────────────────────────────────┐
│ Layer 2: Indexing & Retrieval (Rust Backend)                │
│  ┌──────────────────────────────────────────────────────┐   │
│  │ Wiki File System                                     │   │
│  │  • WikiFileSystem: .wiki/pages/ management          │   │
│  │  • IndexManager: index.json metadata                │   │
│  │  • GraphManager: graph.json relationships           │   │
│  └──────────────────────────────────────────────────────┘   │
│  ┌──────────────────────────────────────────────────────┐   │
│  │ Search & Retrieval                                   │   │
│  │  • Keyword search (tokenized)                        │   │
│  │  • Semantic search (vector embeddings)               │   │
│  │  • Graph traversal (BFS, shortest path)             │   │
│  └──────────────────────────────────────────────────────┘   │
│  ┌──────────────────────────────────────────────────────┐   │
│  │ Graph Algorithms                                     │   │
│  │  • PageRank (influence scoring)                      │   │
│  │  • Louvain (community detection)                     │   │
│  │  • Centrality (degree, betweenness)                  │   │
│  │  • Dijkstra (shortest paths)                         │   │
│  └──────────────────────────────────────────────────────┘   │
│  ┌──────────────────────────────────────────────────────┐   │
│  │ Document Processing                                  │   │
│  │  • Ingest pipeline (parse → chunk → embed → store)  │   │
│  │  • Markdown chunking (heading-aware)                 │   │
│  │  • Metadata extraction                               │   │
│  └──────────────────────────────────────────────────────┘   │
└─────────────────────────────────────────────────────────────┘
                            ↓
┌─────────────────────────────────────────────────────────────┐
│ Layer 3: Storage Layer (Global + Project-Local)             │
│  ┌──────────────────────────────────────────────────────┐   │
│  │ Global Storage (~/.opencode-llm-wiki/)               │   │
│  │  • .vectors/.store/      - Deduplicated vectors     │   │
│  │  • .hash_index.json      - Content hash index       │   │
│  │  • .ref_counter.db       - Reference counting       │   │
│  │  • .projects/.registry   - Project registry         │   │
│  └──────────────────────────────────────────────────────┘   │
│  ┌──────────────────────────────────────────────────────┐   │
│  │ Project-Local Storage (.llm-wiki/)                   │   │
│  │  • pages/                - Markdown wiki files       │   │
│  │  • index.json            - Page metadata             │   │
│  │  • graph.json            - Relationships             │   │
│  │  • ruvector/graph/       - Project graph data        │   │
│  └──────────────────────────────────────────────────────┘   │
│  • VectorStorage trait with project filtering              │
│  • RuVector 2.2.0: Vector + Graph + GNN unified storage    │
│  • 30%+ storage savings via deduplication                  │
└─────────────────────────────────────────────────────────────┘

Key Design Principles:

Multiple Interfaces: HTTP API for programmatic access, CLI for automation, MCP for AI agents
Global Storage: Vectors deduplicated across projects at ~/.opencode-llm-wiki/
Hybrid Architecture: Vectors global (deduplicated), graph data project-local (isolated)
Metadata-Driven: index.json manages page metadata, graph.json stores relationships
Pluggable Storage: VectorStorage trait enables easy backend migration
Clean Separation: Interface layer has no business logic, storage layer has no retrieval logic

Features

Core Backend (Production Rust)

✅ 3-Layer Architecture — Clean separation: Interface → Services → Storage
✅ Global Storage with Deduplication — 30%+ storage savings via content-based vector deduplication
✅ RuVector Integration — Unified vector + graph + GNN storage (2048-dimensional embeddings)
✅ Multi-Project Support — Cross-project search and knowledge sharing
✅ Graph Algorithms — PageRank, Louvain community detection, Dijkstra shortest paths, centrality analysis
✅ Vector Semantic Search — Fast ANN retrieval with cosine similarity
✅ Knowledge Graph — Automatic link extraction, relationship mapping, graph traversal
✅ Markdown-Aware Chunking — Heading-path preservation, configurable overlap
✅ Multi-Provider LLM — OpenAI, Anthropic, OpenRouter, custom endpoints
✅ HTTP API + CLI — Axum server (port 19828) + standalone CLI tools
✅ MCP Protocol — 11 tools for AI agent integration
✅ Async-First Design — tokio runtime, non-blocking I/O

Graph Analytics (Phase 2)

✅ PageRank — Identify influential pages (damping factor 0.85, 100 iterations)
✅ Community Detection — Louvain algorithm for topic clustering (modularity optimization)
✅ Centrality Metrics — Degree centrality, betweenness centrality for bridge node detection
✅ Shortest Paths — Dijkstra algorithm with path reconstruction
✅ Graph Insights API — Isolated pages, bridge nodes, graph statistics
✅ Deep Research — Multi-hop semantic search with BFS traversal
✅ Cypher Queries — Basic graph query support (MATCH, CREATE, RETURN)

MCP Tools (11 Available)

Tool	Purpose
`wiki_read`	Read a single wiki page by path
`wiki_list`	List all wiki pages with metadata
`wiki_search`	Keyword search across wiki content
`wiki_query_with_context`	Intelligent context injection (keyword + vector)
`wiki_get_graph`	Get knowledge graph (nodes and edges)
`wiki_graph_insights`	Analyze graph structure (PageRank, communities, centrality)
`wiki_deep_research`	Multi-hop reasoning with graph traversal
`wiki_get_index`	Get content catalog (index.md)
`wiki_get_overview`	Get global summary (overview.md)
`wiki_get_purpose`	Get wiki goals and scope (purpose.md)
`wiki_ingest`	Ingest documents into knowledge base

API Endpoints (16 Available)

Document Management

POST /api/ingest - Ingest documents into wiki
POST /api/pages - List all wiki pages
POST /api/pages/read - Read specific page content
POST /api/pages/search - Keyword search across pages

Graph Operations

POST /api/graph - Get full knowledge graph
POST /api/graph/insights - Graph analysis (PageRank, communities, centrality)
POST /api/research - Deep research with multi-hop traversal

Metadata

POST /api/meta/index - Wiki page catalog
POST /api/meta/overview - Graph statistics
POST /api/meta/purpose - Wiki purpose and structure

Search & Query

POST /api/search - Semantic vector search
POST /api/query - Query with intelligent context injection

Health & Status

GET /health - Health check endpoint

Tech Stack

Layer	Technology	Purpose
Storage	RuVector 2.2.0	Vector + Graph + GNN unified storage
Embedding	OpenRouter API	2048-dim embeddings (nvidia/llama-nemotron)
Chunking	Custom Rust	Markdown heading-aware splitting
HTTP Server	Axum + tokio	Async Rust web framework
CLI	clap	Command-line interface
MCP Server	Node.js + @modelcontextprotocol/sdk	AI agent integration
Graph Algorithms	Pure Rust	PageRank, Louvain, Dijkstra, centrality

Installation

Prerequisites

Rust 1.70+ (for backend)
Node.js 20+ (for MCP server)
API Key (OpenRouter, OpenAI, or Anthropic for embeddings)

Build from Source

# Clone repository
git clone https://github.com/yourusername/opencode-llm-wiki.git
cd opencode-llm-wiki

# Build Rust backend
cargo build --release

# Install MCP server dependencies
cd src-mcp
npm install
cd ..

Configuration

Create ~/.config/opencode-llm-wiki/llm-wiki.jsonc:

{
  "contextModel": "anthropic/claude-opus-4.6",
  "embeddingModel": "openrouter/nvidia/llama-nemotron-embed-vl-1b-v2:free",
  "embeddingDimension": 2048,
  
  "providers": {
    "openrouter": {
      "options": {
        "apiKey": "sk-or-v1-...",
        "baseURL": "https://openrouter.ai/api/v1"
      }
    },
    "anthropic": {
      "options": {
        "apiKey": "sk-ant-...",
        "baseURL": "https://api.anthropic.com/v1"
      }
    }
  },
  
  "storage": {
    "backend": "ruvector",
    "path": "./data/ruvector"
  }
}

Quick Start

1. Start HTTP API Server

cargo run --release --bin llm-wiki-server
# Server listening on http://127.0.0.1:19828

2. Use CLI Tools

# Initialize new wiki
cargo run --release --bin llm-wiki -- init my-wiki

# Ingest documents
cargo run --release --bin llm-wiki -- ingest docs/ --recursive

# Query knowledge base
cargo run --release --bin llm-wiki -- query "vector database architecture"

3. Use MCP Server (with Claude Desktop)

Add to claude_desktop_config.json:

{
  "mcpServers": {
    "llm-wiki": {
      "command": "node",
      "args": ["/path/to/opencode-llm-wiki/src-mcp/src/index.js"],
      "env": {
        "WIKI_API_URL": "http://127.0.0.1:19828"
      }
    }
  }
}

4. Use HTTP API

# Health check
curl http://127.0.0.1:19828/health

# List pages
curl -X POST http://127.0.0.1:19828/api/pages \
  -H "Content-Type: application/json" \
  -d '{"scope":"global"}'

# Graph insights
curl -X POST http://127.0.0.1:19828/api/graph/insights \
  -H "Content-Type: application/json" \
  -d '{"analysis_type":"stats","scope":"global"}'

# Deep research
curl -X POST http://127.0.0.1:19828/api/research \
  -H "Content-Type: application/json" \
  -d '{"query":"RuVector integration","max_depth":2,"max_results":5}'

Project Structure

Wiki Project Structure

my-wiki/
├── purpose.md              # Wiki goals and scope
├── .wiki/
│   ├── pages/              # All wiki pages (markdown)
│   └── _meta/
│       ├── index.json      # Page metadata
│       └── graph.json      # Knowledge graph
└── data/
    └── ruvector/           # Vector database storage

Codebase Structure

opencode-llm-wiki/
├── src/                    # Rust backend (3-layer architecture)
│   ├── api/                # Layer 1: HTTP API + handlers
│   │   ├── state.rs        # AppState (dependency injection)
│   │   ├── handlers.rs     # Request handlers
│   │   ├── routes.rs       # Route definitions
│   │   └── server.rs       # Axum server
│   ├── services/           # Layer 2: Business logic
│   │   ├── embedding.rs    # Embedding API client
│   │   ├── chunking.rs     # Markdown chunking
│   │   ├── ingest.rs       # Document ingestion
│   │   ├── query.rs        # Search + context optimization
│   │   └── llm_client.rs   # Multi-provider LLM client
│   ├── storage/            # Layer 3: Data abstraction
│   │   ├── traits.rs       # VectorStorage trait
│   │   └── ruvector_impl.rs # RuVector implementation
│   ├── wiki/               # Wiki-specific logic
│   │   ├── filesystem.rs   # File system operations
│   │   ├── graph.rs        # Graph management
│   │   ├── graph_algorithms.rs # PageRank, Louvain, etc.
│   │   └── cypher.rs       # Cypher query engine
│   ├── types/              # Shared types
│   ├── main.rs             # API server binary
│   └── cli.rs              # CLI tools binary
├── src-mcp/                # MCP server (Node.js)
│   └── src/
│       ├── index.js        # MCP server entry point
│       ├── server.js       # Tool definitions
│       └── lib/
│           └── core-api-client.js # HTTP API client
├── docs/                   # Documentation
│   ├── RELEASE_v1.0.1.md   # Release notes
│   ├── V1.0.1_VERIFICATION.md # Verification report
│   └── RUVECTOR_PHASE2_COMPLETE.md # Phase 2 completion
└── benches/                # Performance benchmarks

Credits & Inspiration

Foundational Methodology: Andrej Karpathy's LLM Wiki Pattern — The core three-layer architecture (Raw Sources → Wiki → Schema) and incremental compilation philosophy.

Vector Storage: RuVector — Unified vector + graph + GNN storage backend with self-organizing neural architecture.

What We Built: A production Rust backend implementing Karpathy's pattern with graph-native design and advanced graph algorithms (PageRank, community detection, centrality analysis).

Performance

Benchmarks (v1.0.1)

Vector Search (1000 vectors): ~2ms average
PageRank (62 nodes): <50ms
Community Detection (62 nodes): <100ms
BFS Traversal (depth=3): <20ms
Betweenness Centrality (62 nodes): <150ms
API Response Time: 5-300ms (depends on operation)

Test Coverage

Total Tests: 61
Pass Rate: 100%
Categories: Storage layer, graph algorithms, API handlers, services

Roadmap

v1.1.0 (Planned)

[ ] Advanced Cypher query support (WHERE, ORDER BY, aggregations)
[ ] Real-time graph updates via WebSocket
[ ] Multi-language embedding support
[ ] Incremental indexing (avoid full re-ingestion)
[ ] Graph visualization UI

Future

[ ] Desktop client (Tauri-based, separate repository)
[ ] Web interface (React-based)
[ ] Browser extension (web clipper)
[ ] Docker deployment
[ ] Kubernetes support

License

This project is licensed under the GNU General Public License v3.0 — see LICENSE for details.

Star History