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