# Librarian MCP Server

An intelligent document management MCP server that leverages mental models and orchestration patterns to provide context-aware document storage, retrieval, and analysis.

## Overview

The Librarian MCP Server is part of the cos mcp ecosystem and implements sophisticated document management capabilities using the Model Context Protocol. It features:

- **Intelligent Classification**: Multi-dimensional document analysis
- **Mental Model Integration**: Leverages frameworks from the MCP Orchestrator
- **Proactive Assistance**: Pattern detection and organization suggestions
- **Flexible Storage**: Adapter pattern for multiple storage backends
- **Semantic Search**: Natural language document retrieval

## Architecture

Built using patterns from the MCP Orchestrator:
- Classification Engine for multi-dimensional analysis
- Intent Router for operation routing
- Storage Adapters for backend flexibility
- Proactive patterns for intelligent suggestions

See [ARCHITECTURE.md](./ARCHITECTURE.md) for detailed design documentation.

## Installation

```bash
npm install
npm run build
```

## Usage

### Run the Server

```bash
npm start
```

### Configure with Claude Desktop

Add to your Claude Desktop configuration:

```json
{
  "mcpServers": {
    "librarian": {
      "command": "node",
      "args": ["/path/to/librarian/dist/index.js"]
    }
  }
}
```

## Available Tools

### Document Management

- **store_document**: Store documents with automatic classification
- **search_documents**: Search using natural language or filters
- **get_document**: Retrieve specific documents
- **update_document**: Update document content or metadata
- **delete_document**: Remove documents from library

### Analysis & Organization

- **analyze_document**: Apply mental models for document analysis
- **organize_library**: AI-driven document organization

## Examples

### Store a Document
```javascript
{
  "tool": "store_document",
  "arguments": {
    "content": "# Project Plan\n\nThis document outlines...",
    "metadata": {
      "title": "Q1 2024 Project Plan",
      "author": "John Doe",
      "tags": ["planning", "quarterly"]
    },
    "options": {
      "autoClassify": true,
      "detectDuplicates": true
    }
  }
}
```

### Search Documents
```javascript
{
  "tool": "search_documents",
  "arguments": {
    "query": "project plans from last quarter",
    "filters": {
      "domain": ["business"],
      "dateRange": {
        "start": "2024-01-01"
      }
    },
    "options": {
      "semantic": true,
      "limit": 5
    }
  }
}
```

### Analyze Document
```javascript
{
  "tool": "analyze_document",
  "arguments": {
    "documentId": "doc-123",
    "analysisType": "summary",
    "framework": "swot"
  }
}
```

## Integration with MCP Orchestrator

The Librarian can be integrated with the MCP Orchestrator for advanced workflows:

1. Use orchestrator to analyze complex queries
2. Route document operations through mental models
3. Chain multiple operations for sophisticated workflows

Example orchestrated workflow:
```
1. Gather intent about document needs
2. Search relevant documents
3. Analyze using appropriate mental models
4. Organize based on patterns
5. Generate insights
```

## Development

### Project Structure
```
librarian/
├── src/
│   ├── adapters/      # Storage backend adapters
│   ├── engines/       # Classification and analysis engines
│   ├── tools/         # MCP tool definitions
│   ├── types.ts       # TypeScript type definitions
│   ├── LibrarianServer.ts  # Main server implementation
│   └── index.ts       # Entry point
├── ARCHITECTURE.md    # Detailed architecture documentation
├── package.json
└── README.md
```

### Adding New Features

1. **New Storage Backend**: Implement the `StorageAdapter` interface
2. **New Analysis Type**: Add to `AnalysisType` enum and implement handler
3. **New Organization Method**: Add to `OrganizeMethod` and implement logic

### Testing

```bash
# Run in development mode
npm run dev

# Test with MCP Inspector
npx @modelcontextprotocol/inspector dist/index.js
```

## Future Enhancements

- [ ] PostgreSQL adapter with vector embeddings
- [ ] Integration with filesystem MCP for local files
- [ ] Browser MCP integration for web content
- [ ] Real-time collaboration features
- [ ] Advanced duplicate detection
- [ ] Custom mental model definitions
- [ ] Batch import/export capabilities

## License

MIT

## Contributing

Contributions welcome! Please follow the existing patterns and ensure TypeScript compilation succeeds before submitting PRs.