rbt-mcp-server 0.3.0

MCP Server for Graphiti memory and document chunking with intelligent Markdown processing.

KnowledgeSmith MCP Server

MCP Server for Graphiti memory and document chunking. Previously included RBT document editing tools (now archived).

📦 Archive Notice

RBT Document Editor Tools (Archived 2025-10-09)

The RBT document editing功能已於 2025-10-09 封存，改用原生 Claude Code Read/Edit/Write 工具以降低維護成本和 token 使用。

封存內容：

• document_service.py - 文件服務
• document_parser.py - 文件解析器
• 11 個 editor MCP 工具（get_outline, read_content, update_block 等）
• templates/ - 文件模板
• cache.py - 文件快取

保留功能：

• ✅ chunking/ - 文件分塊與同步功能
• ✅ graphiti_tools.py - Graphiti 記憶體功能（8 個工具）

如何恢復封存的代碼：

# 查看封存版本
git show v-with-editor

# 恢復特定檔案
git checkout v-with-editor -- rbt_mcp_server/document_service.py

# 或建立分支使用完整封存版本
git checkout -b restore-editor v-with-editor

🎯 Current Features

Graphiti Knowledge Graph Integration

• Intelligent Chunking: Automatically split documents into semantic chunks based on document structure (sections for RBT, H3 headings for Markdown)
• Incremental Sync: Only update changed chunks, preserving unchanged content
• Neo4j Backend: Store document chunks as episodes in Graphiti knowledge graph
• graphiti-memory Compatible: Drop-in replacement with same search_nodes/search_facts API
• 8 MCP Tools: add_document, search_memory_nodes, search_memory_facts, get_episodes, delete_episode, get_entity_edge, delete_entity_edge, clear_graph

📦 Installation

Prerequisites

1. Setup Neo4j Database

Using Docker (recommended):

docker run \
  -p 7474:7474 \
  -p 7687:7687 \
  -e NEO4J_AUTH=neo4j/your-password \
  --name neo4j \
  neo4j:latest

Verify at: http://localhost:7474

2. Get OpenAI API Key

Required for Graphiti embeddings and graph operations.

Install MCP Server

Option 1: Install from source (uv)

# Clone repository
git clone https://github.com/yourusername/KnowledgeSmith.git
cd KnowledgeSmith

# Install with uv
uv pip install -e .

Option 2: Direct installation

uv pip install rbt-mcp-server

🚀 Quick Start

1. Configure Claude Desktop

Add to ~/Library/Application Support/Claude/claude_desktop_config.json:

{
  "mcpServers": {
    "graphiti-memory-server": {
      "type": "stdio",
      "command": "rbt-mcp-server",
      "env": {
        "RBT_ROOT_DIR": "/path/to/your/document/root",
        "NEO4J_URI": "bolt://localhost:7687",
        "NEO4J_USER": "neo4j",
        "NEO4J_PASSWORD": "your-password",
        "OPENAI_API_KEY": "your-openai-api-key"
      }
    }
  }
}

Required Environment Variables:

• RBT_ROOT_DIR: Root directory for document comparison (required for add_document tool)
• NEO4J_URI, NEO4J_USER, NEO4J_PASSWORD: Neo4j database connection
• OPENAI_API_KEY: OpenAI API key for Graphiti embeddings

Or use full uv command:

{
  "mcpServers": {
    "graphiti-memory-server": {
      "type": "stdio",
      "command": "uv",
      "args": ["run", "rbt-mcp-server"],
      "env": {
        "RBT_ROOT_DIR": "/path/to/your/document/root",
        "NEO4J_URI": "bolt://localhost:7687",
        "NEO4J_USER": "neo4j",
        "NEO4J_PASSWORD": "your-password",
        "OPENAI_API_KEY": "your-openai-api-key"
      }
    }
  }
}

2. Set Environment Variables (Optional - if not using Claude Desktop)

# Required for add_document tool
export RBT_ROOT_DIR=/path/to/your/document/root

# Required for Graphiti integration
export NEO4J_URI=bolt://localhost:7687
export NEO4J_USER=neo4j
export NEO4J_PASSWORD=your-password
export OPENAI_API_KEY=your-openai-api-key

3. Test the Server

rbt-mcp-server

📚 Available MCP Tools

Document Management

1. add_document - Sync documents to knowledge graph with automatic chunking
   • Supports Markdown (chunked by H3 headings) and RBT documents
   • Incremental sync: only updates changed chunks

Knowledge Graph Query

2. search_memory_nodes - Search knowledge graph nodes (entities, preferences, procedures)
3. search_memory_facts - Search knowledge graph facts (relationships)
4. get_episodes - Retrieve recent memory episodes

Data Management

5. delete_episode - Delete specific episode
6. get_entity_edge - Get entity relationship edge by UUID
7. delete_entity_edge - Delete entity relationship edge
8. clear_graph - Clear all data from knowledge graph (⚠️ irreversible)

🔗 Graphiti Integration Usage

Adding Documents to Knowledge Graph

General Markdown Documents:

add_document(
    new_file_path="/absolute/path/to/document.md",
    project_id="my-project",
    file_path="docs/guide.md"  # relative path for general docs
)

RBT Documents (REQ/BP/TASK):

add_document(
    new_file_path="/absolute/path/to/TASK-001.md",
    project_id="knowledge-smith",
    feature_id="my-feature",
    rbt_type="TASK",
    file_path="001"  # task number for TASK documents
)

Searching Knowledge

# Search for nodes (entities, preferences, procedures)
results = await search_nodes(
    query="documentation preferences",
    group_ids=["knowledge-smith"],
    entity="Preference",
    max_nodes=10
)

# Search for facts (relationships)
facts = await search_facts(
    query="task dependencies",
    group_ids=["knowledge-smith"],
    max_facts=10
)

Difference from graphiti-memory MCP

This MCP server extends the original graphiti-memory MCP with document chunking capabilities:

• Original graphiti-memory: Stores entire documents as single episodes
• This MCP (graphiti-chunk-mcp): Automatically chunks documents into semantic sections
  • RBT documents: Split by section (sec-*)
  • Markdown documents: Split by H3 headings (###)
  • Incremental updates: Only sync changed chunks

API Compatibility: All search_nodes, search_facts, get_episodes functions maintain the same interface as graphiti-memory.

📖 Documentation

• Markdown Writing Guide - How to write Markdown documents that work well with the chunker
• MCP Installation Guide - Detailed installation and usage instructions

🧪 Development

Install development dependencies:

uv sync --dev

Run tests:

RBT_ROOT_DIR=/test/root uv run pytest -v

Test coverage:

RBT_ROOT_DIR=/test/root uv run pytest --cov=rbt_mcp_server --cov-report=html

📝 License

MIT License

🤝 Contributing

Contributions welcome! Please open an issue or submit a pull request.