## 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 Tools API Reference

Complete reference for the Model Context Protocol (MCP) server tools and resources.

## Overview

The kogral-mcp server implements the MCP protocol (JSON-RPC 2.0) for Claude Code integration. It provides:

- 10 Tools: Operations for querying and modifying knowledge base (7 core + 3 block tools)
- 6 Resources: Access to knowledge graph content via URIs
- 2 Prompts: Guided workflows for common tasks

## Server Configuration

### Start MCP Server

    # Stdio transport (local use)
    kb serve

    # Or run directly
    kb-mcp serve

### Claude Code Configuration

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

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

## Tools

### kb/search

Search the knowledge base using text and/or semantic similarity.

Input Schema:

    {
      "type": "object",
      "properties": {
        "query": {
          "type": "string",
          "description": "Search query"
        },
        "type": {
          "type": "string",
          "enum": ["note", "decision", "guideline", "pattern", "journal", "execution", "all"],
          "description": "Filter by node type",
          "default": "all"
        },
        "project": {
          "type": "string",
          "description": "Limit search to specific project graph"
        },
        "semantic": {
          "type": "boolean",
          "description": "Enable semantic similarity search",
          "default": true
        },
        "threshold": {
          "type": "number",
          "description": "Minimum similarity threshold (0-1)",
          "default": 0.4
        },
        "limit": {
          "type": "integer",
          "description": "Maximum number of results",
          "default": 10
        }
      },
      "required": ["query"]
    }

Example Request:

    {
      "jsonrpc": "2.0",
      "id": 1,
      "method": "kogral/search",
      "params": {
        "query": "error handling patterns in Rust",
        "type": "pattern",
        "semantic": true,
        "threshold": 0.6,
        "limit": 5
      }
    }

Example Response:

    {
      "jsonrpc": "2.0",
      "id": 1,
      "result": {
        "type": "text",
        "text": "Found 3 result(s):\n\n1. Error Handling with thiserror (pattern, score: 0.85)\n   Tags: rust, error-handling\n   Created: 2026-01-15\n   \n2. Result Type Best Practices (guideline, score: 0.72)\n   Tags: rust, error-handling, best-practices\n   Created: 2026-01-10\n\n3. Custom Error Types (note, score: 0.65)\n   Tags: rust, error-handling\n   Created: 2026-01-08"
      }
    }

### kb/add_note

Add a new note to the knowledge base.

Input Schema:

    {
      "type": "object",
      "properties": {
        "title": {
          "type": "string",
          "description": "Note title"
        },
        "content": {
          "type": "string",
          "description": "Note content (markdown)"
        },
        "tags": {
          "type": "array",
          "items": { "type": "string" },
          "description": "Tags for categorization",
          "default": []
        },
        "relates_to": {
          "type": "array",
          "items": { "type": "string" },
          "description": "Related node IDs",
          "default": []
        },
        "project": {
          "type": "string",
          "description": "Project graph name",
          "default": "default"
        }
      },
      "required": ["title", "content"]
    }

Example Request:

    {
      "jsonrpc": "2.0",
      "id": 2,
      "method": "kogral/add_note",
      "params": {
        "title": "Async Trait Patterns",
        "content": "Common patterns for using async traits in Rust:\n\n1. Use `async-trait` crate\n2. Box return types for flexibility\n3. Consider Send + Sync bounds",
        "tags": ["rust", "async", "patterns"],
        "relates_to": ["pattern-error-handling"]
      }
    }

Example Response:

    {
      "jsonrpc": "2.0",
      "id": 2,
      "result": {
        "type": "text",
        "text": "Note added successfully: note-async-trait-patterns (ID: note-abc123)"
      }
    }

### kb/add_decision

Create an Architectural Decision Record (ADR).

Input Schema:

    {
      "type": "object",
      "properties": {
        "title": {
          "type": "string",
          "description": "Decision title"
        },
        "context": {
          "type": "string",
          "description": "Decision context and background"
        },
        "decision": {
          "type": "string",
          "description": "The decision made"
        },
        "consequences": {
          "type": "array",
          "items": { "type": "string" },
          "description": "List of consequences",
          "default": []
        },
        "status": {
          "type": "string",
          "enum": ["proposed", "accepted", "rejected", "deprecated", "superseded"],
          "default": "proposed"
        },
        "tags": {
          "type": "array",
          "items": { "type": "string" },
          "default": []
        }
      },
      "required": ["title", "context", "decision"]
    }

Example Request:

    {
      "jsonrpc": "2.0",
      "id": 3,
      "method": "kogral/add_decision",
      "params": {
        "title": "Use SurrealDB for Knowledge Graph Storage",
        "context": "Need a scalable storage solution that supports graph queries and can handle growing knowledge base",
        "decision": "Adopt SurrealDB as the primary storage backend for production deployments",
        "consequences": [
          "Better query performance for graph traversal",
          "Native support for relationships",
          "Additional infrastructure dependency",
          "Team needs to learn SurrealDB query language"
        ],
        "status": "accepted",
        "tags": ["architecture", "storage", "surrealdb"]
      }
    }

Example Response:

    {
      "jsonrpc": "2.0",
      "id": 3,
      "result": {
        "type": "text",
        "text": "Decision added: decision-use-surrealdb (ID: decision-xyz789)\nStatus: accepted"
      }
    }

### kb/link

Create a relationship between two nodes.

Input Schema:

    {
      "type": "object",
      "properties": {
        "from": {
          "type": "string",
          "description": "Source node ID"
        },
        "to": {
          "type": "string",
          "description": "Target node ID"
        },
        "relation": {
          "type": "string",
          "enum": ["relates_to", "depends_on", "implements", "extends", "supersedes", "explains"],
          "description": "Relationship type"
        },
        "strength": {
          "type": "number",
          "description": "Relationship strength (0-1)",
          "minimum": 0,
          "maximum": 1,
          "default": 1.0
        }
      },
      "required": ["from", "to", "relation"]
    }

Example Request:

    {
      "jsonrpc": "2.0",
      "id": 4,
      "method": "kogral/link",
      "params": {
        "from": "note-async-trait-patterns",
        "to": "pattern-error-handling",
        "relation": "relates_to",
        "strength": 0.8
      }
    }

Example Response:

    {
      "jsonrpc": "2.0",
      "id": 4,
      "result": {
        "type": "text",
        "text": "Link created: note-async-trait-patterns --[relates_to]--> pattern-error-handling (strength: 0.8)"
      }
    }

Relationship Types:

- `relates_to`: General conceptual relationship
- `depends_on`: Dependency (from depends on to)
- `implements`: Implementation of concept/pattern
- `extends`: Inherits or extends another node
- `supersedes`: Replaces an older version
- `explains`: Provides documentation/clarification

### kb/get_guidelines

Retrieve guidelines for current project with inheritance resolution.

Input Schema:

    {
      "type": "object",
      "properties": {
        "language": {
          "type": "string",
          "description": "Programming language (e.g., rust, nushell)"
        },
        "category": {
          "type": "string",
          "description": "Guideline category (e.g., error-handling, testing)"
        },
        "include_base": {
          "type": "boolean",
          "description": "Include shared/base guidelines",
          "default": true
        }
      }
    }

Example Request:

    {
      "jsonrpc": "2.0",
      "id": 5,
      "method": "kogral/get_guidelines",
      "params": {
        "language": "rust",
        "category": "error-handling",
        "include_base": true
      }
    }

Example Response:

    {
      "jsonrpc": "2.0",
      "id": 5,
      "result": {
        "type": "text",
        "text": "Guidelines for rust/error-handling:\n\n## Project Guidelines (priority: 150)\n\n1. Custom Error Types (guideline-custom-errors)\n   - Use thiserror for error definitions\n   - Implement From traits for conversions\n   - Source: .kogral/guidelines/rust-errors.md\n\n## Shared Guidelines (priority: 50)\n\n1. Result Type Best Practices (guideline-result-best-practices)\n   - Always use Result<T> for fallible operations\n   - Never use unwrap() in production\n   - Source: ~/Tools/.kogral-shared/guidelines/rust-errors.md\n\n2. Error Propagation (guideline-error-propagation)\n   - Use ? operator for error propagation\n   - Add context with .context()\n   - Source: ~/Tools/.kogral-shared/guidelines/rust-errors.md"
      }
    }

### kb/list_graphs

List available knowledge graphs.

Input Schema:

    {
      "type": "object",
      "properties": {}
    }

Example Request:

    {
      "jsonrpc": "2.0",
      "id": 6,
      "method": "kb/list_graphs"
    }

Example Response:

    {
      "jsonrpc": "2.0",
      "id": 6,
      "result": {
        "type": "text",
        "text": "Available graphs:\n\n- default (Current project)\n  Path: /path/to/project/.kogral\n  Nodes: 42\n  Last modified: 2026-01-17T10:30:00Z\n\n- shared (Shared guidelines)\n  Path: ~/Tools/.kogral-shared\n  Nodes: 156\n  Last modified: 2026-01-15T14:20:00Z"
      }
    }

### kb/export

Export knowledge base to various formats.

Input Schema:

    {
      "type": "object",
      "properties": {
        "format": {
          "type": "string",
          "enum": ["logseq", "json", "markdown"],
          "description": "Export format"
        },
        "output_path": {
          "type": "string",
          "description": "Output file or directory path"
        },
        "include_types": {
          "type": "array",
          "items": {
            "type": "string",
            "enum": ["note", "decision", "guideline", "pattern", "journal", "execution"]
          },
          "description": "Node types to include",
          "default": ["note", "decision", "guideline", "pattern"]
        },
        "skip_journals": {
          "type": "boolean",
          "default": true
        }
      },
      "required": ["format", "output_path"]
    }

Example Request:

    {
      "jsonrpc": "2.0",
      "id": 7,
      "method": "kogral/export",
      "params": {
        "format": "logseq",
        "output_path": "/Users/akasha/logseq-graph",
        "include_types": ["note", "decision", "guideline"],
        "skip_journals": true
      }
    }

Example Response:

    {
      "jsonrpc": "2.0",
      "id": 7,
      "result": {
        "type": "text",
        "text": "Export completed:\n\nFormat: Logseq\nOutput: /Users/akasha/logseq-graph\nExported: 42 nodes\n  - 23 notes\n  - 12 decisions\n  - 7 guidelines\n\nLogseq graph ready to open."
      }
    }

## Block Tools

Tools for querying Logseq content blocks. Requires `blocks.enable_mcp_tools = true` in configuration.

### kb/find_blocks

Find blocks by tag, task status, or custom property across the knowledge base.

Input Schema:

    {
      "type": "object",
      "properties": {
        "tag": {
          "type": "string",
          "description": "Find blocks with this tag (e.g., 'card', 'important')"
        },
        "status": {
          "type": "string",
          "enum": ["TODO", "DOING", "DONE", "LATER", "NOW", "WAITING", "CANCELLED"],
          "description": "Find blocks with this task status"
        },
        "property_key": {
          "type": "string",
          "description": "Custom property key to search for"
        },
        "property_value": {
          "type": "string",
          "description": "Custom property value to match"
        },
        "limit": {
          "type": "integer",
          "description": "Maximum number of results",
          "default": 20
        }
      }
    }

Note: Provide one of: `tag`, `status`, or both `property_key` and `property_value`.

Example Request (find blocks by tag):

    {
      "jsonrpc": "2.0",
      "id": 8,
      "method": "kogral/find_blocks",
      "params": {
        "tag": "high-priority",
        "limit": 10
      }
    }

Example Response:

    {
      "jsonrpc": "2.0",
      "id": 8,
      "result": {
        "type": "text",
        "text": "Found 3 blocks with tag '#high-priority':\n\n**Project Tasks** (project-tasks-123)\n  - TODO Implement authentication #high-priority\n  - TODO Fix security vulnerability #high-priority\n\n**Sprint Planning** (sprint-planning-456)\n  - DOING Refactor database layer #high-priority"
      }
    }

Example Request (find blocks by property):

    {
      "jsonrpc": "2.0",
      "id": 9,
      "method": "kogral/find_blocks",
      "params": {
        "property_key": "priority",
        "property_value": "high",
        "limit": 15
      }
    }

### kb/find_todos

Find all TODO blocks across the knowledge base.

Input Schema:

    {
      "type": "object",
      "properties": {
        "limit": {
          "type": "integer",
          "description": "Maximum number of results",
          "default": 20
        }
      }
    }

Example Request:

    {
      "jsonrpc": "2.0",
      "id": 10,
      "method": "kogral/find_todos",
      "params": {
        "limit": 25
      }
    }

Example Response:

    {
      "jsonrpc": "2.0",
      "id": 10,
      "result": {
        "type": "text",
        "text": "Found 8 TODO blocks:\n\n**Project Tasks** (project-tasks-123)\n  - TODO Implement authentication\n  - TODO Write integration tests\n  - TODO Update documentation\n\n**Bug Fixes** (bug-fixes-456)\n  - TODO Fix race condition in cache\n  - TODO Address memory leak\n\n**Research** (research-789)\n  - TODO Evaluate GraphQL alternatives\n  - TODO Benchmark new approach\n  - TODO Document findings"
      }
    }

### kb/find_cards

Find all flashcard blocks (blocks tagged with #card) for spaced repetition learning.

Input Schema:

    {
      "type": "object",
      "properties": {
        "limit": {
          "type": "integer",
          "description": "Maximum number of flashcards",
          "default": 10
        }
      }
    }

Example Request:

    {
      "jsonrpc": "2.0",
      "id": 11,
      "method": "kogral/find_cards",
      "params": {
        "limit": 5
      }
    }

Example Response:

    {
      "jsonrpc": "2.0",
      "id": 11,
      "result": {
        "type": "text",
        "text": "Found 3 flashcards:\n\n**Rust Learning** (rust-learning-123)\n  - What is Rust's ownership model? #card #rust\n    - Ownership prevents data races at compile time\n    - Each value has a single owner\n\n**System Design** (system-design-456)\n  - What is the CAP theorem? #card #distributed-systems\n    - Consistency, Availability, Partition tolerance\n    - Can only guarantee 2 of 3\n\n**Algorithms** (algorithms-789)\n  - What is the time complexity of quicksort? #card #algorithms\n    - Average: O(n log n)\n    - Worst case: O(n²)"
      }
    }

Use Cases:

- kb/find_blocks: General block search by metadata
- kb/find_todos: Task management and tracking
- kb/find_cards: Spaced repetition learning system

See Also:

- Logseq Blocks Support
- ADR-004: Logseq Blocks Support

## Resources

Resources provide read-only access to knowledge graph content via URIs.

### kogral://project/notes

Access project notes.

URI: `kogral://project/notes` or `kogral://project/notes/{note-id}`

Example: Read all project notes

    kogral://project/notes

Example: Read specific note

    kogral://project/notes/async-trait-patterns

### kogral://project/decisions

Access project decisions (ADRs).

URI: `kogral://project/decisions` or `kogral://project/decisions/{decision-id}`

### kogral://project/guidelines

Access project-specific guidelines.

URI: `kogral://project/guidelines` or `kogral://project/guidelines/{guideline-id}`

### kogral://project/patterns

Access project patterns.

URI: `kogral://project/patterns` or `kogral://project/patterns/{pattern-id}`

### kogral://shared/guidelines

Access shared guidelines (inherited).

URI: `kogral://shared/guidelines` or `kogral://shared/guidelines/{guideline-id}`

### kogral://shared/patterns

Access shared patterns (inherited).

URI: `kogral://shared/patterns` or `kogral://shared/patterns/{pattern-id}`

## Prompts

Prompts provide guided workflows for common tasks.

### kb/summarize_project

Generate a comprehensive project knowledge summary.

Arguments:

    {
      "project": {
        "type": "string",
        "description": "Project graph name",
        "default": "default"
      }
    }

Example Request:

    {
      "jsonrpc": "2.0",
      "id": 8,
      "method": "kogral/summarize_project",
      "params": {
        "project": "default"
      }
    }

Returns: Prompt messages with project summary including:

- Total node counts by type
- Recent additions
- Top tags
- Key decisions
- Active patterns

### kb/find_related

Find nodes related to a specific topic or node.

Arguments:

    {
      "node_id": {
        "type": "string",
        "description": "Node ID to find relations for"
      },
      "depth": {
        "type": "integer",
        "description": "Maximum traversal depth",
        "default": 2
      }
    }

Example Request:

    {
      "jsonrpc": "2.0",
      "id": 9,
      "method": "kb/find_related",
      "params": {
        "node_id": "pattern-error-handling",
        "depth": 2
      }
    }

Returns: Prompt messages with:

- Direct relationships
- Indirect relationships (depth 2+)
- Common tags
- Related guidelines

## Error Handling

### Error Codes

Standard JSON-RPC 2.0 error codes:

Code | Meaning | Description
--- | --- | ---
-32700 | Parse error | Invalid JSON
-32600 | Invalid Request | Missing required fields
-32601 | Method not found | Unknown tool/resource
-32602 | Invalid params | Parameter validation failed
-32603 | Internal error | Server-side error

### Example Error Response

    {
      "jsonrpc": "2.0",
      "id": 1,
      "error": {
        "code": -32602,
        "message": "Invalid params",
        "data": {
          "details": "Field 'query' is required but missing",
          "field": "query"
        }
      }
    }

## Best Practices

### 1. Use Semantic Search for Discovery

    {
      "method": "kogral/search",
      "params": {
        "query": "how to handle database connection errors",
        "semantic": true,
        "threshold": 0.5
      }
    }

### 2. Link Related Concepts

    {
      "method": "kogral/link",
      "params": {
        "from": "note-new-discovery",
        "to": "pattern-related-pattern",
        "relation": "implements"
      }
    }

### 3. Query Guidelines Before Implementation

    {
      "method": "kogral/get_guidelines",
      "params": {
        "language": "rust",
        "category": "testing"
      }
    }

### 4. Document Decisions with ADRs

    {
      "method": "kogral/add_decision",
      "params": {
        "title": "Use X for Y",
        "context": "Background...",
        "decision": "We will...",
        "consequences": ["Pro 1", "Con 1"]
      }
    }

## See Also

- MCP Specification
- Quick Start Guide
- Configuration Reference
- kb-mcp Source Code