lorehub/docs/mcp-tools-complete.md

Capture and surface the collective wisdom of your codebase

# LoreHub MCP Tools - Complete Implementation

## Overview
The LoreHub MCP server now provides a comprehensive set of tools for knowledge management, including full CRUD operations on facts, relationship management, and detailed project analytics.

## Implemented Tools

### 1. Read Operations ✅
- **search_facts**: Search facts with wildcards and filters
- **list_facts**: List facts with type/service filtering
- **get_fact**: Get a single fact by ID
- **list_projects**: List all projects

### 2. Fact Management ✅
- **create_fact**: Create new facts (auto-creates projects if needed)
- **update_fact**: Update existing facts
- **delete_fact**: Permanently delete facts (requires confirmation)
- **archive_fact**: Soft delete facts
- **restore_fact**: Restore archived facts

### 3. Relation Management ✅
- **create_relation**: Create relationships between facts
- **delete_relation**: Remove relationships
- **list_relations**: List all relationships for a fact

### 4. Analytics ✅
- **get_project_stats**: Get comprehensive project statistics

## Key Features

### Auto-Project Initialization
When creating a fact for a non-existent project, the system automatically:
1. Creates the project using the provided path
2. Extracts the project name from the path
3. Creates the fact in the new project
4. Returns a special message indicating both actions

### Relation Types
Supported relationship types:
- `succeeds`: One lore supersedes/replaces another
- `challenges`: Lores are in conflict/contradiction
- `supports`: Lores reinforce each other
- `depends_on`: One lore requires another
- `bound_to`: General relationship between lores

### Project Statistics
The `get_project_stats` tool provides:
- Total facts count
- Facts by type breakdown
- Facts by status (active/completed/archived)
- Facts by service (for monorepos)
- Average confidence level
- High/low confidence fact counts
- Recent facts (last 5)
- Fact growth metrics (week/month/quarter)
- Top 10 tags by frequency
- Relation statistics

## Example Usage

### Creating Facts
```json
{
  "tool": "create_fact",
  "arguments": {
    "project_path": "/path/to/project",
    "content": "Use PostgreSQL for data storage",
    "why": "Need ACID compliance and complex queries",
    "type": "decision",
    "confidence": 90,
    "tags": ["database", "architecture"]
  }
}
```

### Creating Relations
```json
{
  "tool": "create_relation",
  "arguments": {
    "from_fact_id": "fact-123",
    "to_fact_id": "fact-456",
    "type": "depends_on",
    "strength": 0.8
  }
}
```

### Getting Project Stats
```json
{
  "tool": "get_project_stats",
  "arguments": {
    "project_path": "/path/to/project"
  }
}
```

## MCP Configuration
Add to Claude Desktop's MCP settings:

```json
{
  "mcpServers": {
    "lorehub": {
      "command": "lorehub-mcp"
    }
  }
}
```

## Future Enhancements (Low Priority)
- **bulk_create_facts**: Create multiple facts at once
- **search_by_tags**: Advanced tag-based search
- **export_project**: Export project data
- **import_facts**: Bulk import from JSON/YAML

## Architecture Notes

### Safety Features
1. **Confirmation Required**: Destructive operations like `delete_fact` require explicit confirmation
2. **Validation**: All operations validate that facts/projects exist before proceeding
3. **Cross-Project Protection**: Relations can only be created between facts in the same project
4. **Soft Delete**: Archive operation preserves data while marking it inactive

### Performance Considerations
- Statistics are calculated on-demand
- Relation deduplication prevents counting bidirectional relations twice
- Tag frequency analysis limited to top 10 for efficiency
- Recent facts limited to 5 most recent

### Error Handling
Clear error messages for common scenarios:
- "Project not found at path: X"
- "Fact not found with ID: Y"
- "Cannot create relation between facts in different projects"
- "Deletion must be confirmed by setting confirm: true"
- "Fact is already archived"
- "Fact is not archived"

## Testing
All tools have comprehensive unit tests covering:
- Happy path scenarios
- Error conditions
- Edge cases
- Data validation

Run tests with: `npm test src/mcp/server.test.ts`