# Ollama Hive MCP Server

A TypeScript-based Model Context Protocol (MCP) server that integrates with Ollama models using LangChain. This server provides tools and resources for querying local language models through a standardized MCP interface, with model-specific MCP server configurations.

## Features

- **Model Management**: Configure and manage multiple Ollama models
- **Model-Specific MCPs**: Each model can have its own set of MCP servers
- **Session Management**: Conversation sessions for context continuity across multiple queries
- **Environment Variable Support**: Override endpoints and configuration via environment variables
- **LangChain Integration**: Leverage LangChain for model interactions
- **Environment-based Configuration**: Load configuration from `MCP_CONFIG_PATH`
- **MCP Tools**: Query models, test connectivity, and list available models
- **MCP Resources**: Access model configurations and metadata
- **Stdio Transport**: Standard input/output communication for seamless integration
- **Pre-configured Models**: Define models with their specific endpoints and settings
- **Model Pre-loading**: All models are loaded at startup for quick responses
- **Performance Monitoring**: Built-in response time tracking and status monitoring

## Quick Start with NPX

Run the server directly with npx (no installation required):

```bash
# Basic usage
npx ollama-hive-mcp-server

# With custom configuration
MCP_CONFIG_PATH=./my-config.json npx ollama-hive-mcp-server

# With environment overrides
OLLAMA_ENDPOINT=http://localhost:11434 MCP_CONFIG_PATH=./config.json npx ollama-hive-mcp-server
```

## Simplified Interface

The server provides a clean, simplified interface:

### Tools Available
- `query_model` - Query pre-configured models with optional session context
- `test_model` - Test model connectivity
- `get_model_info` - Get model details and MCP info
- `list_models` - List all configured models
- `get_config_summary` - Configuration overview
- `get_loading_status` - Model loading status
- `create_session` - Create conversation sessions for context continuity
- `list_sessions` - List all active conversation sessions
- `get_session` - Get detailed session information and message history
- `delete_session` - Delete specific conversation sessions
- `clear_sessions` - Clear all conversation sessions

### Example Usage
```json
{
  "tool": "query_model",
  "arguments": {
    "prompt": "Hello, world!"
  }
}

{
  "tool": "query_model", 
  "arguments": {
    "model": "llama3.2",
    "prompt": "Write a Python function to calculate fibonacci"
  }
}

{
  "tool": "query_model",
  "arguments": {
    "prompt": "Explain quantum computing",
    "createSession": true
  }
}
```

### Session-Based Conversations
```json
{
  "tool": "create_session",
  "arguments": {
    "modelName": "llama3.2",
    "title": "Coding Session"
  }
}

{
  "tool": "query_model",
  "arguments": {
    "sessionId": "your-session-id",
    "prompt": "Write a Python function to calculate fibonacci"
  }
}

{
  "tool": "query_model",
  "arguments": {
    "sessionId": "your-session-id", 
    "prompt": "Now add error handling to that function"
  }
}
```

Models use their pre-configured settings (temperature, endpoint, MCP servers) automatically. Sessions maintain conversation context for natural, multi-turn interactions.

## Documentation

- **[Session Management Guide](SESSION_GUIDE.md)** - Complete guide to using conversation sessions
- **[Testing Guide](TESTING.md)** - Comprehensive testing and validation instructions
- **[Logging System](LOGGING.md)** - MCP-compatible logging system documentation

## Prerequisites

- Node.js 18+ 
- Ollama running locally (default: `http://localhost:11434`)
- TypeScript knowledge for customization

## Installation

1. Clone the repository:
```bash
git clone <repository-url>
cd ollama-hive
```

2. Install dependencies:
```bash
npm install
```

3. Build the project:
```bash
npm run build
```

## Configuration

### Environment Variables

Set the following environment variables to configure the server:

```bash
# Required: Path to your MCP configuration file
export MCP_CONFIG_PATH=/path/to/your/mcp-config.json

# Optional: Override Ollama endpoint for all models
export OLLAMA_ENDPOINT=http://localhost:11434

# Optional: Enable debug logging
export DEBUG=true

# Optional: Set Node environment
export NODE_ENV=production
```

### Configuration File Format

Create a JSON configuration file with the following structure:

```json
{
  "globalEndpoint": "http://localhost:11434",
  "models": [
    {
      "name": "llama3.2",
      "endpoint": "http://custom-endpoint:11434",
      "model": "llama3.2:latest", 
      "temperature": 0.7,
      "maxTokens": 2048,
      "description": "Llama 3.2 model for general purpose tasks",
      "mcps": [
        {
          "name": "filesystem-server",
          "command": "npx",
          "args": ["-y", "@modelcontextprotocol/server-filesystem", "/allowed/path"],
          "description": "Filesystem access MCP server",
          "env": {
            "NODE_ENV": "production"
          }
        }
      ]
    }
  ],
  "defaultModel": "llama3.2"
}
```

#### Configuration Fields

**Global Configuration:**
- `globalEndpoint`: Default endpoint for all models (optional)
- `defaultModel`: Name of the default model to use (optional)

**Model Configuration:**
- `name`: Unique identifier for the model (required)
- `endpoint`: Model-specific endpoint override (optional)
- `model`: Ollama model name (required, e.g., `llama3.2:latest`)
- `temperature`: Response generation temperature 0.0-2.0 (optional, default: 0.7)
- `maxTokens`: Maximum tokens to generate (optional)
- `description`: Human-readable description (optional)
- `mcps`: Array of MCP servers for this model (optional, default: [])

**MCP Server Configuration:**
- `name`: Unique identifier for the MCP server (required)
- `command`: Command to execute the server (required)
- `args`: Command line arguments (optional)
- `env`: Environment variables for the server (optional)
- `description`: Human-readable description (optional)

### Endpoint Resolution Priority

The server resolves endpoints in the following priority order:

1. `OLLAMA_ENDPOINT` environment variable (highest priority)
2. Model-specific `endpoint` configuration
3. Global `globalEndpoint` configuration
4. Default: `http://localhost:11434` (lowest priority)

### Example Configuration

See `config/example-mcp-config.json` for a complete example with multiple models and their associated MCP servers.

## Usage

### Starting the Server

```bash
# Set configuration path
export MCP_CONFIG_PATH=./config/example-mcp-config.json

# Optional: Override Ollama endpoint
export OLLAMA_ENDPOINT=http://localhost:11434

# Start the server
npm start
```

### Development Mode

```bash
npm run dev
```

### Using MCP Inspector

Test your server with the MCP Inspector:

```bash
npm run inspector
```

## Available Tools

### `query_model`

Query a configured Ollama model with a prompt.

**Parameters:**
- `prompt` (required): The prompt to send to the model
- `model` (optional): Model name (uses default if not specified)
- `sessionId` (optional): Session ID for conversation context
- `createSession` (optional): Auto-create a new session if no sessionId provided (enables automatic conversation continuity)

**Example:**
```json
{
  "model": "llama3.2",
  "prompt": "Explain the concept of Model Context Protocol",
  "createSession": true
}
```

**Session Examples:**
```json
// Auto-create session for conversation continuity
{
  "prompt": "Write a Python function",
  "createSession": true
}

// Use existing session
{
  "prompt": "Now add error handling to that function",
  "sessionId": "existing-session-id"
}
```

### `test_model`

Test connectivity to a specific model and its MCP connections.

**Parameters:**
- `model` (required): Name of the model to test

**Example:**
```json
{
  "model": "llama3.2"
}
```

### `get_model_info`

Get detailed information about a model and its MCP servers.

**Parameters:**
- `model` (required): Name of the model to get info for

**Example:**
```json
{
  "model": "codellama"
}
```

### `list_models`

List all available configured models with their MCP counts.

**Parameters:** None

### `get_config_summary`

Get configuration summary including environment overrides.

**Parameters:** None

## Available Resources

### `model://list`

Returns a list of all configured models with resolved endpoints and availability status.

### `model://default`

Returns the default model configuration.

### `model://{name}`

Returns configuration for a specific model by name.

### `config://summary`

Returns configuration summary with environment overrides.

### `config://environment`

Returns current environment configuration.

## Integration Examples

### With Claude Desktop

Add to your Claude Desktop configuration:

```json
{
  "mcpServers": {
    "ollama-hive": {
      "command": "node",
      "args": ["/path/to/ollama-hive/dist/index.js"],
      "env": {
        "MCP_CONFIG_PATH": "/path/to/your/config.json",
        "OLLAMA_ENDPOINT": "http://localhost:11434"
      }
    }
  }
}
```

### With Cursor IDE

Configure in Cursor's MCP settings:

```json
{
  "servers": {
    "ollama-hive": {
      "command": "node",
      "args": ["/path/to/ollama-hive/dist/index.js"],
      "env": {
        "MCP_CONFIG_PATH": "/path/to/your/config.json",
        "OLLAMA_ENDPOINT": "http://localhost:11434"
      }
    }
  }
}
```

### Environment File Setup

Create a `.env` file in your project root:

```bash
MCP_CONFIG_PATH=./config/example-mcp-config.json
OLLAMA_ENDPOINT=http://localhost:11434
DEBUG=false
NODE_ENV=development
```

## Model-Specific MCPs

Each model can have its own set of MCP servers, allowing for specialized toolsets:

- **General Purpose Model**: Filesystem, web search, memory tools
- **Code Model**: GitHub integration, filesystem for code, documentation tools  
- **Research Model**: Web search, academic databases, reference tools
- **Creative Model**: Image generation, creative writing tools

This allows you to tailor the available tools to each model's intended use case.

## Error Handling

The server includes comprehensive error handling:

- **Configuration Errors**: Invalid JSON or missing required fields
- **Environment Errors**: Missing or invalid environment variables
- **Model Errors**: Connection failures or invalid model names
- **MCP Errors**: MCP server connection or tool execution failures
- **Tool Errors**: Invalid parameters or execution failures

All errors are returned in a standardized format with detailed error messages.

## Development

### Project Structure

```
src/
├── index.ts           # Main server implementation
├── config.ts          # Configuration loader with environment support
├── langchain-manager.ts # LangChain model management with MCP integration
└── types.ts           # TypeScript type definitions

config/
└── example-mcp-config.json # Example configuration
```

### Building

```bash
npm run build
```

### Watching for Changes

```bash
npm run watch
```

### Type Checking

The project uses strict TypeScript settings with comprehensive type safety.

## Security Considerations

- **Model Access**: Only configured models are accessible
- **MCP Isolation**: Each model's MCPs are isolated from others
- **Configuration Validation**: All configuration is validated using Zod schemas
- **Environment Variable Security**: Sensitive data can be passed via environment variables
- **Error Sanitization**: Error messages are sanitized to prevent information leakage

## Performance

- **Connection Reuse**: Model connections are reused across requests
- **Lazy Loading**: Models and MCPs are initialized only when first accessed
- **Environment Caching**: Environment configuration is cached at startup
- **Memory Management**: Efficient memory usage with proper cleanup

## Troubleshooting

### Common Issues

1. **"Configuration not loaded" Error**
   - Ensure `MCP_CONFIG_PATH` is set correctly
   - Verify the configuration file exists and is valid JSON

2. **"Model not found" Error**
   - Check that Ollama is running on the configured endpoint
   - Verify the model name matches the Ollama model exactly
   - Check endpoint resolution order

3. **Connection Timeout**
   - Ensure Ollama server is accessible
   - Check firewall settings if using remote endpoints
   - Verify `OLLAMA_ENDPOINT` environment variable if set

4. **MCP Server Connection Issues**
   - Check MCP server command and arguments
   - Verify environment variables for MCP servers
   - Check that MCP packages are installed

### Debug Mode

Enable debug logging:

```bash
export DEBUG=true
npm start
```

## Contributing

1. Fork the repository
2. Create a feature branch
3. Make your changes
4. Add tests if applicable
5. Submit a pull request

## License

MIT License - see LICENSE file for details.

## Related Projects

- [Model Context Protocol](https://modelcontextprotocol.io/)
- [MCP TypeScript SDK](https://github.com/modelcontextprotocol/typescript-sdk)
- [LangChain](https://js.langchain.com/)
- [Ollama](https://ollama.ai/)

## Support

For questions and support:

- Create an issue in the repository
- Check the [MCP documentation](https://modelcontextprotocol.io/)
- Review the [LangChain documentation](https://js.langchain.com/)