19 KiB
19 KiB
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)
kogral serve
# Or run directly
kogral-mcp serve
Claude Code Configuration
Add to ~/.config/claude/config.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:
{
"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"
}
}
kogral/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)"
}
}
kogral/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"
}
}
kogral/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 relationshipdepends_on: Dependency (from depends on to)implements: Implementation of concept/patternextends: Inherits or extends another nodesupersedes: Replaces an older versionexplains: Provides documentation/clarification
kogral/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"
}
}
kogral/list_graphs
List available knowledge graphs.
Input Schema:
{
"type": "object",
"properties": {}
}
Example Request:
{
"jsonrpc": "2.0",
"id": 6,
"method": "kogral/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"
}
}
kogral/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.
kogral/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
}
}
kogral/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"
}
}
kogral/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:
- kogral/find_blocks: General block search by metadata
- kogral/find_todos: Task management and tracking
- kogral/find_cards: Spaced repetition learning system
See Also:
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.
kogral/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
kogral/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": "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
{
"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"]
}
}