4.4 KiB
API Reference
API documentation for the Knowledge Base system.
Available APIs
- MCP Tools - Model Context Protocol tools and resources for Claude Code integration
- Rust API - kogral-core library API for programmatic access
Overview
The Knowledge Base system provides multiple API layers:
MCP Protocol
JSON-RPC 2.0 protocol for Claude Code integration:
- 7 Tools for interacting with knowledge base
- 6 Resources for accessing knowledge graphs
- 2 Prompts for guided workflows
See MCP Tools for complete reference.
Rust Library
Direct programmatic access via kogral-core:
use kb_core::prelude::*;
// Load a graph
let storage = FilesystemStorage::new(".kogral")?;
let graph = storage.load_graph("default").await?;
// Query nodes
let results = graph.nodes.values()
.filter(|n| n.tags.contains(&"rust".to_string()))
.collect::<Vec<_>>();
See Rust API for complete reference.
Quick Reference
Common MCP Operations
// Search knowledge base
{
"jsonrpc": "2.0",
"method": "kogral/search",
"params": {
"query": "error handling",
"type": "guideline",
"semantic": true
}
}
// Add a note
{
"jsonrpc": "2.0",
"method": "kogral/add_note",
"params": {
"title": "New Discovery",
"content": "Interesting finding about...",
"tags": ["research", "rust"]
}
}
// Get guidelines
{
"jsonrpc": "2.0",
"method": "kogral/get_guidelines",
"params": {
"language": "rust",
"category": "error-handling"
}
}
Common Rust Operations
// Create a new graph
let mut graph = Graph::new("my-project".to_string());
// Add a node
let node = Node {
id: "note-1".to_string(),
node_type: NodeType::Note,
title: "Example Note".to_string(),
content: "Note content".to_string(),
tags: vec!["rust".to_string()],
status: NodeStatus::Active,
// ...
};
graph.add_node(node)?;
// Create a relationship
let edge = Edge::new(
"note-1".to_string(),
"note-2".to_string(),
EdgeType::RelatesTo,
);
graph.add_edge(edge)?;
// Save graph
storage.save_graph(&graph).await?;
Authentication
MCP Server
No authentication required for stdio transport (local use).
For remote access (SSE transport), configure API keys in environment:
export KB_API_KEY="your-api-key"
Rust Library
No authentication needed for local filesystem access.
For SurrealDB backend, configure credentials:
let config = SurrealDbConfig {
url: "ws://localhost:8000".to_string(),
namespace: "kb".to_string(),
database: "default".to_string(),
username: Some("root".to_string()),
password: Some("root".to_string()),
};
let storage = SurrealDbStorage::new(config).await?;
Error Handling
All APIs use structured error types:
MCP Errors
JSON-RPC error responses:
{
"jsonrpc": "2.0",
"id": 1,
"error": {
"code": -32600,
"message": "Invalid request",
"data": {
"details": "Missing required parameter: query"
}
}
}
Error codes:
-32700: Parse error-32600: Invalid request-32601: Method not found-32602: Invalid params-32603: Internal error
Rust Errors
KbError enum with thiserror:
pub enum KbError {
#[error("Storage error: {0}")]
Storage(String),
#[error("Node not found: {0}")]
NodeNotFound(String),
#[error("Invalid configuration: {0}")]
Config(String),
#[error("Parse error: {0}")]
Parse(String),
}
Rate Limiting
MCP server has no rate limiting for local stdio use.
For production deployments with remote access, configure rate limits:
mcp = {
rate_limit = {
enabled = true,
requests_per_minute = 60,
},
}
Versioning
API follows semantic versioning:
- Major version: Breaking changes to API
- Minor version: New features, backward compatible
- Patch version: Bug fixes, backward compatible
Current version: 1.0.0
Deprecation Policy
- Deprecated features marked in documentation
- Minimum 1 major version before removal
- Migration guide provided
Support
- File issues on GitHub
- Check documentation updates
- Join community discussions