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
- For Code Claude Integration: See INTEGRATION_GUIDE.md
- For Usage in Code Claude: See QUICK_REFERENCE.md
- For Adding Documentation: See DOCUMENTATION_GUIDE.md
- For Plugin Doc Template: See PLUGIN_DOCUMENTATION_TEMPLATE.md
- 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)
- 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
- Install dependencies:
pip install -r requirements.txt
- Run the server:
./run_server.sh # Or: python truenas_mcp_server.py
Option 2: Docker Container
- Build the Docker image:
docker-compose build
- 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 architecturetruenas://development/guidelines- Development best practices
Plugin Resources
truenas://plugins/service-types- Guide to service base classestruenas://plugins/patterns- Common plugin patternstruenas://plugins/categories- Categorized plugin listtruenas://plugins/{plugin_name}- Specific plugin documentation
API Resources
truenas://api/versioning- API versioning guidetruenas://api/models- Pydantic model patterns
Testing Resources
truenas://testing/overview- Testing guidetruenas://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
- The server scans the middleware repository for all CLAUDE.md files
- Each file is processed and categorized based on its location
- Content is intelligently summarized to reduce context size
- 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