kogral/docs/apps/mcp-quickguide.md

# 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

```bash
# 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`:

```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

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

# Initialize .kogral directory
kogral init
```

### Step 4: Start Claude Code

```bash
# Start Claude Code (will auto-connect to kogral-mcp)
claude-code
```

### Step 5: Test Connection

In Claude Code, try:

```text
Search for "error handling"
```

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

---

## Essential Commands

### Search Knowledge Base

**Natural language**:

```text
Find notes about Rust error handling
```

**Claude translates to**:

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

### Add Note

**Natural language**:

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

**Claude translates to**:

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

### Add Decision

**Natural language**:

```text
Document decision to use SurrealDB for storage
```

**Claude translates to**:

```json
{
  "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**:

```text
What are our Rust error handling guidelines?
```

**Claude translates to**:

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

### Link Concepts

**Natural language**:

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

**Claude translates to**:

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

---

## Common Workflows

### Capture Meeting Notes

**You**:

```text
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`):

```text
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**:

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

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

```text
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**:

```text
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`):

```text
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**:

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

**Claude** (uses `kogral/summarize_project` prompt):

```text
# 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**:

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

**Claude** (combines `kogral/search` with filtering):

```text
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**:

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

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

```text
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**:

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

**Claude** (uses `kogral/export`):

```text
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:

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

### 4. Review Regularly

Ask Claude for summaries:

```text
What have we documented this week?
```

### 5. Use Semantic Search

For conceptual queries:

```text
Find anything related to "making code maintainable"
```

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

---

## Troubleshooting

### "MCP server not responding"

```bash
# 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"

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

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

### "Permission denied"

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

# Check environment variable
echo $KOGRAL_DIR
```

### "Empty search results"

```bash
# 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](../api/mcp-tools.md) for all available tools
- **Explore**: [Use Cases](../guides/use-cases.md) for more examples
- **Configure**: [Configuration Reference](../config/overview.md) to customize behavior
- **Integrate**: [Claude Code Integration](claude-code.md) 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.