TrueNAS Middleware MCP Server

Servidor MCP Middleware TrueNAS

Este servidor MCP (Model Context Protocol) fornece recursos de documentação otimizados do repositório de middleware TrueNAS para o Code Claude, ajudando-o a entender a estrutura do código e as APIs sem sobrecarga de contexto.

Início Rápido

1. Para Integração com Code Claude: Consulte INTEGRATION_GUIDE.md
2. Para Uso no Code Claude: Consulte QUICK_REFERENCE.md
3. Para Adicionar Documentação: Consulte DOCUMENTATION_GUIDE.md
4. Para Modelo de Documentação de Plugin: Consulte PLUGIN_DOCUMENTATION_TEMPLATE.md
5. Para Planos de Desenvolvimento: Consulte ACTION_PLAN.md

Recursos

• Descobre e processa automaticamente todos os arquivos CLAUDE.md no repositório de middleware
• Organiza a documentação em categorias lógicas (Visão Geral, Plugins, API, Testes, Subsistemas)
• Fornece recursos concisos e focados para evitar sobrecarga de contexto
• Implementa sumarização inteligente de conteúdo

Opções de Configuração

Opção 1: Python Nativo (Recomendado)

1. Crie e ative o ambiente virtual:

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

2. Instale as dependências:

pip install -r requirements.txt

3. Execute o servidor:

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

Opção 2: Contêiner Docker

1. Construa a imagem Docker:

docker-compose build

2. Execute o servidor:

docker-compose run --rm truenas-mcp

Recursos Disponíveis

O servidor fornece os seguintes tipos de recursos:

Recursos de Visão Geral

• truenas://overview - Arquitetura de middleware de alto nível
• truenas://development/guidelines - Melhores práticas de desenvolvimento

Recursos de Plugin

• truenas://plugins/service-types - Guia para classes base de serviço
• truenas://plugins/patterns - Padrões comuns de plugins
• truenas://plugins/categories - Lista categorizada de plugins
• truenas://plugins/{plugin_name} - Documentação específica de plugins

Recursos de API

• truenas://api/versioning - Guia de versionamento de API
• truenas://api/models - Padrões de modelos Pydantic

Recursos de Testes

• truenas://testing/overview - Guia de testes
• truenas://testing/patterns - Padrões comuns de testes

Recursos de Subsistemas

• truenas://subsystems/{name} - Documentação para subsistemas específicos

Integração com Code Claude

Consulte INTEGRATION_GUIDE.md para instruções detalhadas de configuração.

Configuração Rápida (adicione ao claude_desktop_config.json):

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

Como Funciona

1. O servidor verifica o repositório de middleware em busca de todos os arquivos CLAUDE.md
2. Cada arquivo é processado e categorizado com base em sua localização
3. O conteúdo é sumarizado de forma inteligente para reduzir o tamanho do contexto
4. Os recursos são expostos via protocolo MCP para o Code Claude consultar

Estratégia de Otimização

Para evitar sobrecarga de contexto, o servidor:

• Extrai seções-chave da documentação
• Limita exemplos de código aos essenciais
• Foca em assinaturas de API e padrões em vez de implementações completas
• Agrupa informações relacionadas em recursos lógicos

Executando Testes

Os testes são executados usando Docker para garantir um ambiente consistente.

Executar Todos os Testes

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

Executar Arquivo de Teste Específico

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

Executar com Cobertura

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

Executando Testes de Middleware

O servidor inclui uma ferramenta para executar testes de middleware TrueNAS. Use o script run_middleware_tests.sh:

# 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