kogral/docs/api/mcp-tools.md

# 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

```bash
# Stdio transport (local use)
kogral serve

# Or run directly
kogral-mcp serve
```

### Claude Code Configuration

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

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

## Tools

### kogral/search

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

**Input Schema**:

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

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

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

### kogral/add_note

Add a new note to the knowledge base.

**Input Schema**:

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

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

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

### kogral/add_decision

Create an Architectural Decision Record (ADR).

**Input Schema**:

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

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

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

### kogral/link

Create a relationship between two nodes.

**Input Schema**:

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

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

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

### kogral/get_guidelines

Retrieve guidelines for current project with inheritance resolution.

**Input Schema**:

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

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

**Example Response**:

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

### kogral/list_graphs

List available knowledge graphs.

**Input Schema**:

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

**Example Request**:

```json
{
  "jsonrpc": "2.0",
  "id": 6,
  "method": "kogral/list_graphs"
}
```

**Example Response**:

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

### kogral/export

Export knowledge base to various formats.

**Input Schema**:

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

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

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

### kogral/find_blocks

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

**Input Schema**:

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

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

**Example Response**:

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

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

### kogral/find_todos

Find all TODO blocks across the knowledge base.

**Input Schema**:

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

**Example Request**:

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

**Example Response**:

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

### kogral/find_cards

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

**Input Schema**:

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

**Example Request**:

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

**Example Response**:

```json
{
  "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**:
- **kogral/find_blocks**: General block search by metadata
- **kogral/find_todos**: Task management and tracking
- **kogral/find_cards**: Spaced repetition learning system

**See Also**:
- [Logseq Blocks Support](../kogral/core-concepts.md#logseq-content-blocks)
- [ADR-004: Logseq Blocks Support](../architecture/adrs/004-logseq-blocks-support.md)

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

```text
kogral://project/notes
```

**Example**: Read specific note

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

### kogral/summarize_project

Generate a comprehensive project knowledge summary.

**Arguments**:

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

**Example Request**:

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

### kogral/find_related

Find nodes related to a specific topic or node.

**Arguments**:

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

**Example Request**:

```json
{
  "jsonrpc": "2.0",
  "id": 9,
  "method": "kogral/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

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

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

### 2. Link Related Concepts

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

### 3. Query Guidelines Before Implementation

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

### 4. Document Decisions with ADRs

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

## See Also

- [MCP Specification](https://modelcontextprotocol.io/docs)
- [Quick Start Guide](../user-guide/quickstart.md)
- [Configuration Reference](../user-guide/configuration.md)
- [kogral-mcp Source Code](../../crates/kogral-mcp/src/)