TrueNAS Middleware MCP Server

This MCP (Model Context Protocol) server provides optimized documentation resources from the TrueNAS middleware repository to Code Claude, helping it understand the codebase structure and APIs without context overload.

Quick Start

1. For Code Claude Integration: See INTEGRATION_GUIDE.md

2. For Usage in Code Claude: See QUICK_REFERENCE.md

3. For Adding Documentation: See DOCUMENTATION_GUIDE.md

4. For Plugin Doc Template: See PLUGIN_DOCUMENTATION_TEMPLATE.md

5. For Development Plans: See ACTION_PLAN.md

Features

• Automatically discovers and processes all CLAUDE.md files in the middleware repository
• Organizes documentation into logical categories (Overview, Plugins, API, Testing, Subsystems)
• Provides concise, focused resources to avoid context overload
• Implements intelligent content summarization

Setup Options

Option 1: Native Python (Recommended)

1. Create and activate the virtual environment:

python3.11 -m venv venv_tn_mcp
source venv_tn_mcp/bin/activate  # On Windows: venv_tn_mcp\Scripts\activate

2. Install dependencies:

pip install -r requirements.txt

3. Run the server:

./run_server.sh  # Or: python truenas_mcp_server.py

Option 2: Docker Container

1. Build the Docker image:

docker-compose build

2. Run the server:

docker-compose run --rm truenas-mcp

Available Resources

The server provides the following types of resources:

Overview Resources

• `truenas://overview` - High-level middleware architecture
• `truenas://development/guidelines` - Development best practices

Plugin Resources

• `truenas://plugins/service-types` - Guide to service base classes
• `truenas://plugins/patterns` - Common plugin patterns
• `truenas://plugins/categories` - Categorized plugin list
• `truenas://plugins/{plugin_name}` - Specific plugin documentation

API Resources

• `truenas://api/versioning` - API versioning guide
• `truenas://api/models` - Pydantic model patterns

Testing Resources

• `truenas://testing/overview` - Testing guide
• `truenas://testing/patterns` - Common testing patterns

Subsystem Resources

• `truenas://subsystems/{name}` - Documentation for specific subsystems

Integration with Code Claude

See INTEGRATION_GUIDE.md for detailed setup instructions.

Quick Config (add to `claude_desktop_config.json`):

{
  "mcpServers": {
    "truenas-docs": {
      "command": "/path/to/venv_tn_mcp/bin/python",
      "args": ["/path/to/tn_mcp/truenas_mcp_server.py"]
    }
  }
}

How It Works

1. The server scans the middleware repository for all CLAUDE.md files

2. Each file is processed and categorized based on its location

3. Content is intelligently summarized to reduce context size

4. Resources are exposed via MCP protocol for Code Claude to query

Optimization Strategy

To avoid context overload, the server:

• Extracts key sections from documentation
• Limits code examples to essential ones
• Focuses on API signatures and patterns rather than full implementations
• Groups related information into logical resources

Running Tests

Tests are run using Docker to ensure a consistent environment.

Run All Tests

docker-compose run --rm truenas-mcp-test

Run Specific Test File

docker-compose run --rm truenas-mcp-test pytest tests/test_truenas_mcp_tools_server.py -v

Run with Coverage

docker-compose run --rm truenas-mcp-test pytest --cov=. --cov-report=html

Running Middleware Tests

The server includes a tool for running TrueNAS middleware tests. Use the `run_middleware_tests.sh` script:

# Run all middleware tests
./run_middleware_tests.sh

# Run a specific test file
./run_middleware_tests.sh . test_construct_schema.py

# Clean up test container
./run_middleware_tests.sh /path/to/middleware --cleanup