## Keyboard shortcuts

Press `←` or `→` to navigate between chapters

Press `S` or `/` to search in the book

Press `?` to show this help

Press `Esc` to hide this help

# 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

Task | Say to Claude
--- | ---
Search | "Find notes about X"
Add note | "Add a note about X with tags Y, Z"
Add decision | "Document decision to use X for Y"
Get guidelines | "What are our X guidelines?"
Link nodes | "Link A to B as implements"
Summarize | "Summarize project knowledge"
Export | "Export to Logseq format"

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.