MCP Quick Guide

Fast-track guide to integrating KOGRAL with Claude Code via the Model Context Protocol (MCP).

What is MCP?

MCP (Model Context Protocol) is a protocol that allows Claude Code to interact with external tools and data sources. The kogral-mcp server exposes your KOGRAL knowledge base to Claude Code for AI-assisted knowledge management.

Quick Setup (5 Minutes)

Step 1: Build MCP Server

# Build kogral-mcp server
cargo build --package kb-mcp --release

# Verify binary
ls -lh target/release/kb-mcp

Step 2: Configure Claude Code

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

{
  "mcpServers": {
    "kogral-mcp": {
      "command": "/path/to/knowledge-base/target/release/kb-mcp",
      "args": ["serve"],
      "env": {
        "KOGRAL_DIR": "/path/to/your/project/.kogral"
      }
    }
  }
}

Replace /path/to/knowledge-base and /path/to/your/project/.kogral with your actual paths.

Step 3: Initialize KOGRAL

# Navigate to your project
cd /path/to/your/project

# Initialize .kb directory
kb init

Step 4: Start Claude Code

# Start Claude Code (will auto-connect to kb-mcp)
claude-code

Step 5: Test Connection

In Claude Code, try:

Search for "error handling"

Claude will use the kogral/search tool to query your knowledge base.

Essential Commands

Search Knowledge Base

Natural language:

Find notes about Rust error handling

Claude translates to:

{
  "tool": "kogral/search",
  "params": {
    "query": "error handling",
    "type": "note",
    "semantic": true
  }
}

Add Note

Natural language:

Add a note about async Rust patterns with tags rust, async, patterns

Claude translates to:

{
  "tool": "kogral/add_note",
  "params": {
    "title": "Async Rust Patterns",
    "content": "...",
    "tags": ["rust", "async", "patterns"]
  }
}

Add Decision

Natural language:

Document decision to use SurrealDB for storage

Claude translates to:

{
  "tool": "kogral/add_decision",
  "params": {
    "title": "Use SurrealDB for Storage",
    "context": "Need scalable graph database",
    "decision": "Adopt SurrealDB as primary storage backend",
    "consequences": ["Better query performance", "Additional infrastructure"]
  }
}

Get Guidelines

Natural language:

What are our Rust error handling guidelines?

Claude translates to:

{
  "tool": "kogral/get_guidelines",
  "params": {
    "language": "rust",
    "category": "error-handling"
  }
}

Link Concepts

Natural language:

Link note-async-patterns to decision-use-tokio as implements

Claude translates to:

{
  "tool": "kogral/link",
  "params": {
    "from": "note-async-patterns",
    "to": "decision-use-tokio",
    "relation": "implements"
  }
}

Common Workflows

Capture Meeting Notes

You:

We just decided in our meeting to migrate from REST to GraphQL.
Context: current REST API is too chatty, requires multiple round trips.
Consequences: better client performance, but team needs to learn GraphQL.
Create a decision record.

Claude (uses kb/add_decision):

Created decision: decision-migrate-to-graphql

Status: proposed
Context: Current REST API requires multiple round trips (chatty)
Decision: Migrate from REST to GraphQL API
Consequences:
  - ✅ Better client performance
  - ❌ Team learning curve for GraphQL

Find Related Knowledge

You:

I'm working on error handling. What related notes and patterns do we have?

Claude (uses kogral/search with semantic=true):

Found 5 related items:

1. **Error Handling with thiserror** (pattern)
   Tags: rust, error-handling
   Created: 2026-01-15

2. **Result Type Best Practices** (guideline)
   Tags: rust, error-handling, best-practices
   Created: 2026-01-10

3. **Decision: Use anyhow for Application Errors** (decision)
   Status: accepted
   Created: 2026-01-08

4. **Custom Error Types** (note)
   Tags: rust, error-handling
   Created: 2026-01-05

5. **Error Propagation Patterns** (pattern)
   Tags: rust, error-handling
   Created: 2026-01-03

Would you like me to link your current work to any of these?

Document Implementation

You:

I just implemented the user authentication module following our security guidelines.
Add a note and link it to our security guideline.

Claude (uses kb/add_note + kb/link):

Created note: note-user-auth-implementation
Tags: security, authentication, implementation

Linked:
  note-user-auth-implementation --[implements]--> guideline-security-practices

Done! Your implementation is now documented and connected to our guidelines.

Review Project Knowledge

You:

Summarize our project knowledge: what decisions have we made, what patterns are we using?

Claude (uses kb/summarize_project prompt):

# Project Knowledge Summary

**Total Nodes**: 42

## Recent Decisions (5)
- Use SurrealDB for Storage (accepted, 2 days ago)
- Adopt MCP for AI Integration (accepted, 5 days ago)
- Nickel for Configuration (accepted, 1 week ago)

## Active Patterns (8)
- Error Handling with thiserror
- Repository Pattern for DB
- Builder Pattern for Complex Objects
- ...

## Top Tags
1. rust (23 nodes)
2. architecture (12 nodes)
3. error-handling (8 nodes)
4. patterns (7 nodes)

## Guideline Coverage
- Rust: 5 guidelines
- Testing: 3 guidelines
- Security: 2 guidelines

Advanced Usage

Conditional Queries

You:

Find all decisions made in the last week that are still proposed (not accepted)

Claude (combines kogral/search with filtering):

Found 2 proposed decisions from last week:

1. **Migrate to GraphQL** (proposed)
   Created: 3 days ago
   Context: REST API is too chatty...

2. **Add Redis Caching** (proposed)
   Created: 5 days ago
   Context: Database queries are slow...

Would you like to review these and update their status?

Cross-Reference Check

You:

Before I implement X, check if we have any decisions or guidelines about it

Claude (uses kogral/search + kogral/get_guidelines):

Checking existing knowledge about X...

**Decisions**: None found
**Guidelines**: 1 relevant guideline found
  - guideline-module-structure: "Keep modules focused and small"

**Related Notes**: 2 notes mention similar topics
  - note-module-design-patterns
  - note-separation-of-concerns

Recommendation: Your implementation of X looks aligned with our guidelines.
Consider linking it to guideline-module-structure when done.

Export for Sharing

You:

Export our architectural decisions to Logseq so I can review them visually

Claude (uses kb/export):

Exporting to Logseq format...

✓ Exported 12 decisions to /Users/akasha/logseq-export/
  - 12 decision records
  - Preserved wikilinks
  - Added Logseq properties

You can now open /Users/akasha/logseq-export/ in Logseq to visualize the decision graph.

Tips and Tricks

1. Use Natural Language

Don't worry about exact tool syntax. Claude understands:

❌ Don't say: "Use kb/search with query='rust' and type='pattern'" ✅ Do say: "Find Rust patterns in KOGRAL"

2. Be Specific with Tags

When adding notes, use consistent tags:

✅ Good: tags: rust, error-handling, pattern ❌ Bad: tags: Rust, ErrorHandling, patterns

3. Link as You Go

After creating notes, ask Claude to link them:

Link this note to our error handling guideline as 'implements'

4. Review Regularly

Ask Claude for summaries:

What have we documented this week?

5. Use Semantic Search

For conceptual queries:

Find anything related to "making code maintainable"

Not just keyword "maintainable", but concepts like refactoring, clean code, patterns, etc.

Troubleshooting

"MCP server not responding"

# Check kb-mcp is built
ls target/release/kb-mcp

# Test manually
echo '{"jsonrpc":"2.0","id":1,"method":"kogral/search","params":{"query":"test"}}' \
  | target/release/kb-mcp serve

"KB directory not found"

# Verify .kb exists
ls -la /path/to/project/.kogral

# Initialize if missing
cd /path/to/project
kb init

"Permission denied"

# Make binary executable
chmod +x target/release/kb-mcp

# Check environment variable
echo $KOGRAL_DIR

"Empty search results"

# Add some test content
kb add note "Test Note" --content "Test content"

# Try search again in Claude Code

Next Steps

• Read: MCP Tools API Reference for all available tools
• Explore: Use Cases for more examples
• Configure: Configuration Reference to customize behavior
• Integrate: Claude Code Integration for advanced setup

Quick Reference Card

Remember: Claude Code with MCP turns KOGRAL into an active participant in your development workflow. Ask questions, capture decisions, and let AI help you maintain your project's knowledge graph.