jesus/kogral

Fork 0

Jesús Pérez 22e9473e69

chore: add docs

2026-01-23 16:11:07 +00:00

9.5 KiB

Raw Permalink Blame History

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 kogral-mcp --release

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

Step 2: Configure Claude Code

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

{
  "mcpServers": {
    "kogral-mcp": {
      "command": "/path/to/knowledge-base/target/release/kogral-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 .kogral directory
kogral init

Step 4: Start Claude Code

# Start Claude Code (will auto-connect to kogral-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 kogral/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

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 kogral/add_note + kogral/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 kogral/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.

You:

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

Claude (uses kogral/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 kogral/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 kogral-mcp is built
ls target/release/kogral-mcp

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

"KB directory not found"

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

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

"Permission denied"

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

# Check environment variable
echo $KOGRAL_DIR

"Empty search results"

# Add some test content
kogral 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.

9.5 KiB Raw Permalink Blame History

MCP Quick Guide

What is MCP

Quick Setup (5 Minutes)

Step 1: Build MCP Server

Step 2: Configure Claude Code

Step 3: Initialize KOGRAL

Step 4: Start Claude Code

Step 5: Test Connection

Essential Commands

Search Knowledge Base

Add Note

Add Decision

Get Guidelines

Link Concepts

Common Workflows

Capture Meeting Notes

Find Related Knowledge

Document Implementation

Review Project Knowledge

Advanced Usage

Conditional Queries

Cross-Reference Check

Export for Sharing

Tips and Tricks

1. Use Natural Language

2. Be Specific with Tags

3. Link as You Go

4. Review Regularly

5. Use Semantic Search

Troubleshooting

"MCP server not responding"

"KB directory not found"

"Permission denied"

"Empty search results"

Next Steps

Quick Reference Card

9.5 KiB

Raw Permalink Blame History