943 lines
35 KiB
HTML
943 lines
35 KiB
HTML
<!DOCTYPE HTML>
|
|
<html lang="en" class="rust sidebar-visible" dir="ltr">
|
|
<head>
|
|
<!-- Book generated using mdBook -->
|
|
<meta charset="UTF-8">
|
|
<title>Tools Reference - KOGRAL Documentation</title>
|
|
|
|
|
|
<!-- Custom HTML head -->
|
|
|
|
<meta name="description" content="Complete documentation for KOGRAL - Git-native knowledge graphs for developer teams">
|
|
<meta name="viewport" content="width=device-width, initial-scale=1">
|
|
<meta name="theme-color" content="#ffffff">
|
|
|
|
<link rel="icon" href="../favicon.svg">
|
|
<link rel="shortcut icon" href="../favicon.png">
|
|
<link rel="stylesheet" href="../css/variables.css">
|
|
<link rel="stylesheet" href="../css/general.css">
|
|
<link rel="stylesheet" href="../css/chrome.css">
|
|
<link rel="stylesheet" href="../css/print.css" media="print">
|
|
|
|
<!-- Fonts -->
|
|
<link rel="stylesheet" href="../FontAwesome/css/font-awesome.css">
|
|
<link rel="stylesheet" href="../fonts/fonts.css">
|
|
|
|
<!-- Highlight.js Stylesheets -->
|
|
<link rel="stylesheet" id="highlight-css" href="../highlight.css">
|
|
<link rel="stylesheet" id="tomorrow-night-css" href="../tomorrow-night.css">
|
|
<link rel="stylesheet" id="ayu-highlight-css" href="../ayu-highlight.css">
|
|
|
|
<!-- Custom theme stylesheets -->
|
|
|
|
|
|
<!-- Provide site root and default themes to javascript -->
|
|
<script>
|
|
const path_to_root = "../";
|
|
const default_light_theme = "rust";
|
|
const default_dark_theme = "navy";
|
|
</script>
|
|
<!-- Start loading toc.js asap -->
|
|
<script src="../toc.js"></script>
|
|
</head>
|
|
<body>
|
|
<div id="mdbook-help-container">
|
|
<div id="mdbook-help-popup">
|
|
<h2 class="mdbook-help-title">Keyboard shortcuts</h2>
|
|
<div>
|
|
<p>Press <kbd>←</kbd> or <kbd>→</kbd> to navigate between chapters</p>
|
|
<p>Press <kbd>S</kbd> or <kbd>/</kbd> to search in the book</p>
|
|
<p>Press <kbd>?</kbd> to show this help</p>
|
|
<p>Press <kbd>Esc</kbd> to hide this help</p>
|
|
</div>
|
|
</div>
|
|
</div>
|
|
<div id="body-container">
|
|
<!-- Work around some values being stored in localStorage wrapped in quotes -->
|
|
<script>
|
|
try {
|
|
let theme = localStorage.getItem('mdbook-theme');
|
|
let sidebar = localStorage.getItem('mdbook-sidebar');
|
|
|
|
if (theme.startsWith('"') && theme.endsWith('"')) {
|
|
localStorage.setItem('mdbook-theme', theme.slice(1, theme.length - 1));
|
|
}
|
|
|
|
if (sidebar.startsWith('"') && sidebar.endsWith('"')) {
|
|
localStorage.setItem('mdbook-sidebar', sidebar.slice(1, sidebar.length - 1));
|
|
}
|
|
} catch (e) { }
|
|
</script>
|
|
|
|
<!-- Set the theme before any content is loaded, prevents flash -->
|
|
<script>
|
|
const default_theme = window.matchMedia("(prefers-color-scheme: dark)").matches ? default_dark_theme : default_light_theme;
|
|
let theme;
|
|
try { theme = localStorage.getItem('mdbook-theme'); } catch(e) { }
|
|
if (theme === null || theme === undefined) { theme = default_theme; }
|
|
const html = document.documentElement;
|
|
html.classList.remove('rust')
|
|
html.classList.add(theme);
|
|
html.classList.add("js");
|
|
</script>
|
|
|
|
<input type="checkbox" id="sidebar-toggle-anchor" class="hidden">
|
|
|
|
<!-- Hide / unhide sidebar before it is displayed -->
|
|
<script>
|
|
let sidebar = null;
|
|
const sidebar_toggle = document.getElementById("sidebar-toggle-anchor");
|
|
if (document.body.clientWidth >= 1080) {
|
|
try { sidebar = localStorage.getItem('mdbook-sidebar'); } catch(e) { }
|
|
sidebar = sidebar || 'visible';
|
|
} else {
|
|
sidebar = 'hidden';
|
|
}
|
|
sidebar_toggle.checked = sidebar === 'visible';
|
|
html.classList.remove('sidebar-visible');
|
|
html.classList.add("sidebar-" + sidebar);
|
|
</script>
|
|
|
|
<nav id="sidebar" class="sidebar" aria-label="Table of contents">
|
|
<!-- populated by js -->
|
|
<mdbook-sidebar-scrollbox class="sidebar-scrollbox"></mdbook-sidebar-scrollbox>
|
|
<noscript>
|
|
<iframe class="sidebar-iframe-outer" src="../toc.html"></iframe>
|
|
</noscript>
|
|
<div id="sidebar-resize-handle" class="sidebar-resize-handle">
|
|
<div class="sidebar-resize-indicator"></div>
|
|
</div>
|
|
</nav>
|
|
|
|
<div id="page-wrapper" class="page-wrapper">
|
|
|
|
<div class="page">
|
|
<div id="menu-bar-hover-placeholder"></div>
|
|
<div id="menu-bar" class="menu-bar sticky">
|
|
<div class="left-buttons">
|
|
<label id="sidebar-toggle" class="icon-button" for="sidebar-toggle-anchor" title="Toggle Table of Contents" aria-label="Toggle Table of Contents" aria-controls="sidebar">
|
|
<i class="fa fa-bars"></i>
|
|
</label>
|
|
<button id="theme-toggle" class="icon-button" type="button" title="Change theme" aria-label="Change theme" aria-haspopup="true" aria-expanded="false" aria-controls="theme-list">
|
|
<i class="fa fa-paint-brush"></i>
|
|
</button>
|
|
<ul id="theme-list" class="theme-popup" aria-label="Themes" role="menu">
|
|
<li role="none"><button role="menuitem" class="theme" id="default_theme">Auto</button></li>
|
|
<li role="none"><button role="menuitem" class="theme" id="light">Light</button></li>
|
|
<li role="none"><button role="menuitem" class="theme" id="rust">Rust</button></li>
|
|
<li role="none"><button role="menuitem" class="theme" id="coal">Coal</button></li>
|
|
<li role="none"><button role="menuitem" class="theme" id="navy">Navy</button></li>
|
|
<li role="none"><button role="menuitem" class="theme" id="ayu">Ayu</button></li>
|
|
</ul>
|
|
<button id="search-toggle" class="icon-button" type="button" title="Search (`/`)" aria-label="Toggle Searchbar" aria-expanded="false" aria-keyshortcuts="/ s" aria-controls="searchbar">
|
|
<i class="fa fa-search"></i>
|
|
</button>
|
|
</div>
|
|
|
|
<h1 class="menu-title">KOGRAL Documentation</h1>
|
|
|
|
<div class="right-buttons">
|
|
<a href="../print.html" title="Print this book" aria-label="Print this book">
|
|
<i id="print-button" class="fa fa-print"></i>
|
|
</a>
|
|
<a href="https://github.com/your-org/knowledge-base" title="Git repository" aria-label="Git repository">
|
|
<i id="git-repository-button" class="fa fa-github"></i>
|
|
</a>
|
|
<a href="https://github.com/your-org/knowledge-base/edit/main/docs/./api/mcp-tools.md" title="Suggest an edit" aria-label="Suggest an edit">
|
|
<i id="git-edit-button" class="fa fa-edit"></i>
|
|
</a>
|
|
|
|
</div>
|
|
</div>
|
|
|
|
<div id="search-wrapper" class="hidden">
|
|
<form id="searchbar-outer" class="searchbar-outer">
|
|
<input type="search" id="searchbar" name="searchbar" placeholder="Search this book ..." aria-controls="searchresults-outer" aria-describedby="searchresults-header">
|
|
</form>
|
|
<div id="searchresults-outer" class="searchresults-outer hidden">
|
|
<div id="searchresults-header" class="searchresults-header"></div>
|
|
<ul id="searchresults">
|
|
</ul>
|
|
</div>
|
|
</div>
|
|
|
|
<!-- Apply ARIA attributes after the sidebar and the sidebar toggle button are added to the DOM -->
|
|
<script>
|
|
document.getElementById('sidebar-toggle').setAttribute('aria-expanded', sidebar === 'visible');
|
|
document.getElementById('sidebar').setAttribute('aria-hidden', sidebar !== 'visible');
|
|
Array.from(document.querySelectorAll('#sidebar a')).forEach(function(link) {
|
|
link.setAttribute('tabIndex', sidebar === 'visible' ? 0 : -1);
|
|
});
|
|
</script>
|
|
|
|
<div id="content" class="content">
|
|
<main>
|
|
<h1 id="mcp-tools-api-reference"><a class="header" href="#mcp-tools-api-reference">MCP Tools API Reference</a></h1>
|
|
<p>Complete reference for the Model Context Protocol (MCP) server tools and resources.</p>
|
|
<h2 id="overview"><a class="header" href="#overview">Overview</a></h2>
|
|
<p>The kogral-mcp server implements the MCP protocol (JSON-RPC 2.0) for Claude Code integration. It provides:</p>
|
|
<ul>
|
|
<li><strong>10 Tools</strong>: Operations for querying and modifying knowledge base (7 core + 3 block tools)</li>
|
|
<li><strong>6 Resources</strong>: Access to knowledge graph content via URIs</li>
|
|
<li><strong>2 Prompts</strong>: Guided workflows for common tasks</li>
|
|
</ul>
|
|
<h2 id="server-configuration"><a class="header" href="#server-configuration">Server Configuration</a></h2>
|
|
<h3 id="start-mcp-server"><a class="header" href="#start-mcp-server">Start MCP Server</a></h3>
|
|
<pre><code class="language-bash"># Stdio transport (local use)
|
|
kb serve
|
|
|
|
# Or run directly
|
|
kb-mcp serve
|
|
</code></pre>
|
|
<h3 id="claude-code-configuration"><a class="header" href="#claude-code-configuration">Claude Code Configuration</a></h3>
|
|
<p>Add to <code>~/.config/claude/config.json</code>:</p>
|
|
<pre><code class="language-json">{
|
|
"mcpServers": {
|
|
"kogral-mcp": {
|
|
"command": "/path/to/kb-mcp",
|
|
"args": ["serve"],
|
|
"env": {
|
|
"KOGRAL_DIR": "/path/to/project/.kogral"
|
|
}
|
|
}
|
|
}
|
|
}
|
|
</code></pre>
|
|
<h2 id="tools"><a class="header" href="#tools">Tools</a></h2>
|
|
<h3 id="kbsearch"><a class="header" href="#kbsearch">kb/search</a></h3>
|
|
<p>Search the knowledge base using text and/or semantic similarity.</p>
|
|
<p><strong>Input Schema</strong>:</p>
|
|
<pre><code class="language-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"]
|
|
}
|
|
</code></pre>
|
|
<p><strong>Example Request</strong>:</p>
|
|
<pre><code class="language-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
|
|
}
|
|
}
|
|
</code></pre>
|
|
<p><strong>Example Response</strong>:</p>
|
|
<pre><code class="language-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"
|
|
}
|
|
}
|
|
</code></pre>
|
|
<h3 id="kbadd_note"><a class="header" href="#kbadd_note">kb/add_note</a></h3>
|
|
<p>Add a new note to the knowledge base.</p>
|
|
<p><strong>Input Schema</strong>:</p>
|
|
<pre><code class="language-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"]
|
|
}
|
|
</code></pre>
|
|
<p><strong>Example Request</strong>:</p>
|
|
<pre><code class="language-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"]
|
|
}
|
|
}
|
|
</code></pre>
|
|
<p><strong>Example Response</strong>:</p>
|
|
<pre><code class="language-json">{
|
|
"jsonrpc": "2.0",
|
|
"id": 2,
|
|
"result": {
|
|
"type": "text",
|
|
"text": "Note added successfully: note-async-trait-patterns (ID: note-abc123)"
|
|
}
|
|
}
|
|
</code></pre>
|
|
<h3 id="kbadd_decision"><a class="header" href="#kbadd_decision">kb/add_decision</a></h3>
|
|
<p>Create an Architectural Decision Record (ADR).</p>
|
|
<p><strong>Input Schema</strong>:</p>
|
|
<pre><code class="language-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"]
|
|
}
|
|
</code></pre>
|
|
<p><strong>Example Request</strong>:</p>
|
|
<pre><code class="language-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"]
|
|
}
|
|
}
|
|
</code></pre>
|
|
<p><strong>Example Response</strong>:</p>
|
|
<pre><code class="language-json">{
|
|
"jsonrpc": "2.0",
|
|
"id": 3,
|
|
"result": {
|
|
"type": "text",
|
|
"text": "Decision added: decision-use-surrealdb (ID: decision-xyz789)\nStatus: accepted"
|
|
}
|
|
}
|
|
</code></pre>
|
|
<h3 id="kblink"><a class="header" href="#kblink">kb/link</a></h3>
|
|
<p>Create a relationship between two nodes.</p>
|
|
<p><strong>Input Schema</strong>:</p>
|
|
<pre><code class="language-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"]
|
|
}
|
|
</code></pre>
|
|
<p><strong>Example Request</strong>:</p>
|
|
<pre><code class="language-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
|
|
}
|
|
}
|
|
</code></pre>
|
|
<p><strong>Example Response</strong>:</p>
|
|
<pre><code class="language-json">{
|
|
"jsonrpc": "2.0",
|
|
"id": 4,
|
|
"result": {
|
|
"type": "text",
|
|
"text": "Link created: note-async-trait-patterns --[relates_to]--> pattern-error-handling (strength: 0.8)"
|
|
}
|
|
}
|
|
</code></pre>
|
|
<p><strong>Relationship Types</strong>:</p>
|
|
<ul>
|
|
<li><code>relates_to</code>: General conceptual relationship</li>
|
|
<li><code>depends_on</code>: Dependency (from depends on to)</li>
|
|
<li><code>implements</code>: Implementation of concept/pattern</li>
|
|
<li><code>extends</code>: Inherits or extends another node</li>
|
|
<li><code>supersedes</code>: Replaces an older version</li>
|
|
<li><code>explains</code>: Provides documentation/clarification</li>
|
|
</ul>
|
|
<h3 id="kbget_guidelines"><a class="header" href="#kbget_guidelines">kb/get_guidelines</a></h3>
|
|
<p>Retrieve guidelines for current project with inheritance resolution.</p>
|
|
<p><strong>Input Schema</strong>:</p>
|
|
<pre><code class="language-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
|
|
}
|
|
}
|
|
}
|
|
</code></pre>
|
|
<p><strong>Example Request</strong>:</p>
|
|
<pre><code class="language-json">{
|
|
"jsonrpc": "2.0",
|
|
"id": 5,
|
|
"method": "kogral/get_guidelines",
|
|
"params": {
|
|
"language": "rust",
|
|
"category": "error-handling",
|
|
"include_base": true
|
|
}
|
|
}
|
|
</code></pre>
|
|
<p><strong>Example Response</strong>:</p>
|
|
<pre><code class="language-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"
|
|
}
|
|
}
|
|
</code></pre>
|
|
<h3 id="kblist_graphs"><a class="header" href="#kblist_graphs">kb/list_graphs</a></h3>
|
|
<p>List available knowledge graphs.</p>
|
|
<p><strong>Input Schema</strong>:</p>
|
|
<pre><code class="language-json">{
|
|
"type": "object",
|
|
"properties": {}
|
|
}
|
|
</code></pre>
|
|
<p><strong>Example Request</strong>:</p>
|
|
<pre><code class="language-json">{
|
|
"jsonrpc": "2.0",
|
|
"id": 6,
|
|
"method": "kb/list_graphs"
|
|
}
|
|
</code></pre>
|
|
<p><strong>Example Response</strong>:</p>
|
|
<pre><code class="language-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"
|
|
}
|
|
}
|
|
</code></pre>
|
|
<h3 id="kbexport"><a class="header" href="#kbexport">kb/export</a></h3>
|
|
<p>Export knowledge base to various formats.</p>
|
|
<p><strong>Input Schema</strong>:</p>
|
|
<pre><code class="language-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"]
|
|
}
|
|
</code></pre>
|
|
<p><strong>Example Request</strong>:</p>
|
|
<pre><code class="language-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
|
|
}
|
|
}
|
|
</code></pre>
|
|
<p><strong>Example Response</strong>:</p>
|
|
<pre><code class="language-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."
|
|
}
|
|
}
|
|
</code></pre>
|
|
<h2 id="block-tools"><a class="header" href="#block-tools">Block Tools</a></h2>
|
|
<p>Tools for querying Logseq content blocks. Requires <code>blocks.enable_mcp_tools = true</code> in configuration.</p>
|
|
<h3 id="kbfind_blocks"><a class="header" href="#kbfind_blocks">kb/find_blocks</a></h3>
|
|
<p>Find blocks by tag, task status, or custom property across the knowledge base.</p>
|
|
<p><strong>Input Schema</strong>:</p>
|
|
<pre><code class="language-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
|
|
}
|
|
}
|
|
}
|
|
</code></pre>
|
|
<p><strong>Note</strong>: Provide one of: <code>tag</code>, <code>status</code>, or both <code>property_key</code> and <code>property_value</code>.</p>
|
|
<p><strong>Example Request</strong> (find blocks by tag):</p>
|
|
<pre><code class="language-json">{
|
|
"jsonrpc": "2.0",
|
|
"id": 8,
|
|
"method": "kogral/find_blocks",
|
|
"params": {
|
|
"tag": "high-priority",
|
|
"limit": 10
|
|
}
|
|
}
|
|
</code></pre>
|
|
<p><strong>Example Response</strong>:</p>
|
|
<pre><code class="language-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"
|
|
}
|
|
}
|
|
</code></pre>
|
|
<p><strong>Example Request</strong> (find blocks by property):</p>
|
|
<pre><code class="language-json">{
|
|
"jsonrpc": "2.0",
|
|
"id": 9,
|
|
"method": "kogral/find_blocks",
|
|
"params": {
|
|
"property_key": "priority",
|
|
"property_value": "high",
|
|
"limit": 15
|
|
}
|
|
}
|
|
</code></pre>
|
|
<h3 id="kbfind_todos"><a class="header" href="#kbfind_todos">kb/find_todos</a></h3>
|
|
<p>Find all TODO blocks across the knowledge base.</p>
|
|
<p><strong>Input Schema</strong>:</p>
|
|
<pre><code class="language-json">{
|
|
"type": "object",
|
|
"properties": {
|
|
"limit": {
|
|
"type": "integer",
|
|
"description": "Maximum number of results",
|
|
"default": 20
|
|
}
|
|
}
|
|
}
|
|
</code></pre>
|
|
<p><strong>Example Request</strong>:</p>
|
|
<pre><code class="language-json">{
|
|
"jsonrpc": "2.0",
|
|
"id": 10,
|
|
"method": "kogral/find_todos",
|
|
"params": {
|
|
"limit": 25
|
|
}
|
|
}
|
|
</code></pre>
|
|
<p><strong>Example Response</strong>:</p>
|
|
<pre><code class="language-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"
|
|
}
|
|
}
|
|
</code></pre>
|
|
<h3 id="kbfind_cards"><a class="header" href="#kbfind_cards">kb/find_cards</a></h3>
|
|
<p>Find all flashcard blocks (blocks tagged with #card) for spaced repetition learning.</p>
|
|
<p><strong>Input Schema</strong>:</p>
|
|
<pre><code class="language-json">{
|
|
"type": "object",
|
|
"properties": {
|
|
"limit": {
|
|
"type": "integer",
|
|
"description": "Maximum number of flashcards",
|
|
"default": 10
|
|
}
|
|
}
|
|
}
|
|
</code></pre>
|
|
<p><strong>Example Request</strong>:</p>
|
|
<pre><code class="language-json">{
|
|
"jsonrpc": "2.0",
|
|
"id": 11,
|
|
"method": "kogral/find_cards",
|
|
"params": {
|
|
"limit": 5
|
|
}
|
|
}
|
|
</code></pre>
|
|
<p><strong>Example Response</strong>:</p>
|
|
<pre><code class="language-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²)"
|
|
}
|
|
}
|
|
</code></pre>
|
|
<p><strong>Use Cases</strong>:</p>
|
|
<ul>
|
|
<li><strong>kb/find_blocks</strong>: General block search by metadata</li>
|
|
<li><strong>kb/find_todos</strong>: Task management and tracking</li>
|
|
<li><strong>kb/find_cards</strong>: Spaced repetition learning system</li>
|
|
</ul>
|
|
<p><strong>See Also</strong>:</p>
|
|
<ul>
|
|
<li><a href="../kb/core-concepts.html#logseq-content-blocks">Logseq Blocks Support</a></li>
|
|
<li><a href="../architecture/adrs/004-logseq-blocks-support.html">ADR-004: Logseq Blocks Support</a></li>
|
|
</ul>
|
|
<h2 id="resources"><a class="header" href="#resources">Resources</a></h2>
|
|
<p>Resources provide read-only access to knowledge graph content via URIs.</p>
|
|
<h3 id="kogralprojectnotes"><a class="header" href="#kogralprojectnotes">kogral://project/notes</a></h3>
|
|
<p>Access project notes.</p>
|
|
<p><strong>URI</strong>: <code>kogral://project/notes</code> or <code>kogral://project/notes/{note-id}</code></p>
|
|
<p><strong>Example</strong>: Read all project notes</p>
|
|
<pre><code>kogral://project/notes
|
|
</code></pre>
|
|
<p><strong>Example</strong>: Read specific note</p>
|
|
<pre><code>kogral://project/notes/async-trait-patterns
|
|
</code></pre>
|
|
<h3 id="kogralprojectdecisions"><a class="header" href="#kogralprojectdecisions">kogral://project/decisions</a></h3>
|
|
<p>Access project decisions (ADRs).</p>
|
|
<p><strong>URI</strong>: <code>kogral://project/decisions</code> or <code>kogral://project/decisions/{decision-id}</code></p>
|
|
<h3 id="kogralprojectguidelines"><a class="header" href="#kogralprojectguidelines">kogral://project/guidelines</a></h3>
|
|
<p>Access project-specific guidelines.</p>
|
|
<p><strong>URI</strong>: <code>kogral://project/guidelines</code> or <code>kogral://project/guidelines/{guideline-id}</code></p>
|
|
<h3 id="kogralprojectpatterns"><a class="header" href="#kogralprojectpatterns">kogral://project/patterns</a></h3>
|
|
<p>Access project patterns.</p>
|
|
<p><strong>URI</strong>: <code>kogral://project/patterns</code> or <code>kogral://project/patterns/{pattern-id}</code></p>
|
|
<h3 id="kogralsharedguidelines"><a class="header" href="#kogralsharedguidelines">kogral://shared/guidelines</a></h3>
|
|
<p>Access shared guidelines (inherited).</p>
|
|
<p><strong>URI</strong>: <code>kogral://shared/guidelines</code> or <code>kogral://shared/guidelines/{guideline-id}</code></p>
|
|
<h3 id="kogralsharedpatterns"><a class="header" href="#kogralsharedpatterns">kogral://shared/patterns</a></h3>
|
|
<p>Access shared patterns (inherited).</p>
|
|
<p><strong>URI</strong>: <code>kogral://shared/patterns</code> or <code>kogral://shared/patterns/{pattern-id}</code></p>
|
|
<h2 id="prompts"><a class="header" href="#prompts">Prompts</a></h2>
|
|
<p>Prompts provide guided workflows for common tasks.</p>
|
|
<h3 id="kbsummarize_project"><a class="header" href="#kbsummarize_project">kb/summarize_project</a></h3>
|
|
<p>Generate a comprehensive project knowledge summary.</p>
|
|
<p><strong>Arguments</strong>:</p>
|
|
<pre><code class="language-json">{
|
|
"project": {
|
|
"type": "string",
|
|
"description": "Project graph name",
|
|
"default": "default"
|
|
}
|
|
}
|
|
</code></pre>
|
|
<p><strong>Example Request</strong>:</p>
|
|
<pre><code class="language-json">{
|
|
"jsonrpc": "2.0",
|
|
"id": 8,
|
|
"method": "kogral/summarize_project",
|
|
"params": {
|
|
"project": "default"
|
|
}
|
|
}
|
|
</code></pre>
|
|
<p><strong>Returns</strong>: Prompt messages with project summary including:</p>
|
|
<ul>
|
|
<li>Total node counts by type</li>
|
|
<li>Recent additions</li>
|
|
<li>Top tags</li>
|
|
<li>Key decisions</li>
|
|
<li>Active patterns</li>
|
|
</ul>
|
|
<h3 id="kbfind_related"><a class="header" href="#kbfind_related">kb/find_related</a></h3>
|
|
<p>Find nodes related to a specific topic or node.</p>
|
|
<p><strong>Arguments</strong>:</p>
|
|
<pre><code class="language-json">{
|
|
"node_id": {
|
|
"type": "string",
|
|
"description": "Node ID to find relations for"
|
|
},
|
|
"depth": {
|
|
"type": "integer",
|
|
"description": "Maximum traversal depth",
|
|
"default": 2
|
|
}
|
|
}
|
|
</code></pre>
|
|
<p><strong>Example Request</strong>:</p>
|
|
<pre><code class="language-json">{
|
|
"jsonrpc": "2.0",
|
|
"id": 9,
|
|
"method": "kb/find_related",
|
|
"params": {
|
|
"node_id": "pattern-error-handling",
|
|
"depth": 2
|
|
}
|
|
}
|
|
</code></pre>
|
|
<p><strong>Returns</strong>: Prompt messages with:</p>
|
|
<ul>
|
|
<li>Direct relationships</li>
|
|
<li>Indirect relationships (depth 2+)</li>
|
|
<li>Common tags</li>
|
|
<li>Related guidelines</li>
|
|
</ul>
|
|
<h2 id="error-handling"><a class="header" href="#error-handling">Error Handling</a></h2>
|
|
<h3 id="error-codes"><a class="header" href="#error-codes">Error Codes</a></h3>
|
|
<p>Standard JSON-RPC 2.0 error codes:</p>
|
|
<div class="table-wrapper"><table><thead><tr><th>Code</th><th>Meaning</th><th>Description</th></tr></thead><tbody>
|
|
<tr><td>-32700</td><td>Parse error</td><td>Invalid JSON</td></tr>
|
|
<tr><td>-32600</td><td>Invalid Request</td><td>Missing required fields</td></tr>
|
|
<tr><td>-32601</td><td>Method not found</td><td>Unknown tool/resource</td></tr>
|
|
<tr><td>-32602</td><td>Invalid params</td><td>Parameter validation failed</td></tr>
|
|
<tr><td>-32603</td><td>Internal error</td><td>Server-side error</td></tr>
|
|
</tbody></table>
|
|
</div>
|
|
<h3 id="example-error-response"><a class="header" href="#example-error-response">Example Error Response</a></h3>
|
|
<pre><code class="language-json">{
|
|
"jsonrpc": "2.0",
|
|
"id": 1,
|
|
"error": {
|
|
"code": -32602,
|
|
"message": "Invalid params",
|
|
"data": {
|
|
"details": "Field 'query' is required but missing",
|
|
"field": "query"
|
|
}
|
|
}
|
|
}
|
|
</code></pre>
|
|
<h2 id="best-practices"><a class="header" href="#best-practices">Best Practices</a></h2>
|
|
<h3 id="1-use-semantic-search-for-discovery"><a class="header" href="#1-use-semantic-search-for-discovery">1. Use Semantic Search for Discovery</a></h3>
|
|
<pre><code class="language-json">{
|
|
"method": "kogral/search",
|
|
"params": {
|
|
"query": "how to handle database connection errors",
|
|
"semantic": true,
|
|
"threshold": 0.5
|
|
}
|
|
}
|
|
</code></pre>
|
|
<h3 id="2-link-related-concepts"><a class="header" href="#2-link-related-concepts">2. Link Related Concepts</a></h3>
|
|
<pre><code class="language-json">{
|
|
"method": "kogral/link",
|
|
"params": {
|
|
"from": "note-new-discovery",
|
|
"to": "pattern-related-pattern",
|
|
"relation": "implements"
|
|
}
|
|
}
|
|
</code></pre>
|
|
<h3 id="3-query-guidelines-before-implementation"><a class="header" href="#3-query-guidelines-before-implementation">3. Query Guidelines Before Implementation</a></h3>
|
|
<pre><code class="language-json">{
|
|
"method": "kogral/get_guidelines",
|
|
"params": {
|
|
"language": "rust",
|
|
"category": "testing"
|
|
}
|
|
}
|
|
</code></pre>
|
|
<h3 id="4-document-decisions-with-adrs"><a class="header" href="#4-document-decisions-with-adrs">4. Document Decisions with ADRs</a></h3>
|
|
<pre><code class="language-json">{
|
|
"method": "kogral/add_decision",
|
|
"params": {
|
|
"title": "Use X for Y",
|
|
"context": "Background...",
|
|
"decision": "We will...",
|
|
"consequences": ["Pro 1", "Con 1"]
|
|
}
|
|
}
|
|
</code></pre>
|
|
<h2 id="see-also"><a class="header" href="#see-also">See Also</a></h2>
|
|
<ul>
|
|
<li><a href="https://modelcontextprotocol.io/docs">MCP Specification</a></li>
|
|
<li><a href="../user-guide/quickstart.html">Quick Start Guide</a></li>
|
|
<li><a href="../user-guide/configuration.html">Configuration Reference</a></li>
|
|
<li><a href="../../crates/kb-mcp/src/">kb-mcp Source Code</a></li>
|
|
</ul>
|
|
|
|
</main>
|
|
|
|
<nav class="nav-wrapper" aria-label="Page navigation">
|
|
<!-- Mobile navigation buttons -->
|
|
<a rel="prev" href="../api/mcp-protocol.html" class="mobile-nav-chapters previous" title="Previous chapter" aria-label="Previous chapter" aria-keyshortcuts="Left">
|
|
<i class="fa fa-angle-left"></i>
|
|
</a>
|
|
|
|
<a rel="next prefetch" href="../api/mcp-resources.html" class="mobile-nav-chapters next" title="Next chapter" aria-label="Next chapter" aria-keyshortcuts="Right">
|
|
<i class="fa fa-angle-right"></i>
|
|
</a>
|
|
|
|
<div style="clear: both"></div>
|
|
</nav>
|
|
</div>
|
|
</div>
|
|
|
|
<nav class="nav-wide-wrapper" aria-label="Page navigation">
|
|
<a rel="prev" href="../api/mcp-protocol.html" class="nav-chapters previous" title="Previous chapter" aria-label="Previous chapter" aria-keyshortcuts="Left">
|
|
<i class="fa fa-angle-left"></i>
|
|
</a>
|
|
|
|
<a rel="next prefetch" href="../api/mcp-resources.html" class="nav-chapters next" title="Next chapter" aria-label="Next chapter" aria-keyshortcuts="Right">
|
|
<i class="fa fa-angle-right"></i>
|
|
</a>
|
|
</nav>
|
|
|
|
</div>
|
|
|
|
|
|
|
|
|
|
<script>
|
|
window.playground_copyable = true;
|
|
</script>
|
|
|
|
|
|
<script src="../elasticlunr.min.js"></script>
|
|
<script src="../mark.min.js"></script>
|
|
<script src="../searcher.js"></script>
|
|
|
|
<script src="../clipboard.min.js"></script>
|
|
<script src="../highlight.js"></script>
|
|
<script src="../book.js"></script>
|
|
|
|
<!-- Custom JS scripts -->
|
|
|
|
|
|
</div>
|
|
</body>
|
|
</html>
|