230 lines
4.4 KiB
Markdown
230 lines
4.4 KiB
Markdown
# API Reference
|
|
|
|
API documentation for the Knowledge Base system.
|
|
|
|
## Available APIs
|
|
|
|
- [MCP Tools](mcp-tools.md) - Model Context Protocol tools and resources for Claude Code integration
|
|
- [Rust API](rust-api.md) - 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](mcp-tools.md) for complete reference.
|
|
|
|
### Rust Library
|
|
|
|
Direct programmatic access via kogral-core:
|
|
|
|
```rust
|
|
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](rust-api.md) for complete reference.
|
|
|
|
## Quick Reference
|
|
|
|
### Common MCP Operations
|
|
|
|
```json
|
|
// 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
|
|
|
|
```rust
|
|
// 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:
|
|
|
|
```bash
|
|
export KB_API_KEY="your-api-key"
|
|
```
|
|
|
|
### Rust Library
|
|
|
|
No authentication needed for local filesystem access.
|
|
|
|
For SurrealDB backend, configure credentials:
|
|
|
|
```rust
|
|
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:
|
|
|
|
```json
|
|
{
|
|
"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:
|
|
|
|
```rust
|
|
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:
|
|
|
|
```nickel
|
|
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
|
|
|
|
## See Also
|
|
|
|
- [MCP Specification](https://modelcontextprotocol.io/docs)
|
|
- [kogral-core Documentation](../../crates/kogral-core/README.md)
|
|
- [Configuration Reference](../user-guide/configuration.md)
|