Enoch

enoch-mcp

enoch-mcp é um servidor stdio local do Model Context Protocol para uma API de plano de controle Enoch FastAPI configurada. Ele permite que clientes MCP inspecionem e operem o Enoch por meio de ferramentas tipadas, sem expor um shell bruto ou reimplementar a lógica de negócios do Enoch.

repositório do sistema Enoch · Documentação · MCP

O que ele faz

• Registra ferramentas MCP para o plano de controle Enoch, Dashboard V1 e endpoints principais.
• Envia solicitações para uma URL de API Enoch configurada.
• Adiciona Authorization: Bearer <token> às solicitações de API usando o token configurado.
• Retorna respostas da API Enoch ao cliente MCP.
• Marca ferramentas somente leitura com anotações MCP de somente leitura.
• Marca ferramentas de mutação como não somente leitura e adiciona metadados de aprovação.
• Mantém padrões seguros para operações de dry-run.
• Opcionalmente, sonda workers CPU/GPU configurados diretamente por meio de APIs de worker ou diagnósticos SSH na lista de permissões.

O que ele não faz

• Não expõe uma ferramenta de shell bruto.
• Não aceita comandos SSH arbitrários.
• Não lê nem grava arquivos de artefatos locais diretamente.
• Não chama modelos de linguagem.
• Não armazena em cache, tenta novamente, enfileira ou agenda trabalho.
• Não contorna a autenticação ou autorização do Enoch.

Requisitos

• Python 3.11 ou mais recente
• Uma API Enoch em execução, normalmente em http://localhost:8787
• Um token de portador da API Enoch
• Um cliente MCP que possa executar servidores stdio locais

Instalação

Execute a partir do PyPI com uvx:

uvx enoch-mcp --api-url http://localhost:8787 --api-token '<token>'

Ou configure com variáveis de ambiente:

export ENOCH_API_URL='http://localhost:8787'
export ENOCH_API_TOKEN='<token>'
uvx enoch-mcp

Para desenvolvimento local a partir de um checkout:

git clone https://github.com/alias8818/enoch-mcp.git
cd enoch-mcp
uv sync --dev
uv run enoch-mcp --api-url http://localhost:8787 --api-token '<token>'

Configuração

Opção	Variável de ambiente	Padrão	Descrição
--api-url	ENOCH_API_URL	http://localhost:8787	URL base para a API Enoch.
--api-token	ENOCH_API_TOKEN	nenhum	Token de portador para a API Enoch.
--worker-probes-json	ENOCH_WORKER_PROBES_JSON	nenhum	Mapa JSON opcional para diagnósticos diretos de worker.
--worker-probes-file	ENOCH_WORKER_PROBES_FILE	nenhum	Caminho opcional para um mapa JSON para diagnósticos diretos de worker.

O token é obrigatório. Se estiver ausente, as chamadas de ferramenta falham antes de fazer uma solicitação HTTP.

Sondas de worker opcionais

As sondas de worker são desabilitadas a menos que ENOCH_WORKER_PROBES_JSON ou ENOCH_WORKER_PROBES_FILE esteja configurado. Isso mantém o pacote padrão como uma ponte fina de plano de controle. Quando configurado, o MCP expõe diagnósticos nomeados para a verdade do worker: saúde da API, status do painel do worker-gate, marcadores de processo ativos, caudas de log limitadas, espaço em disco e presença esperada de artefatos.

Exemplo:

{
  "cpu": {
    "api_url": "http://127.0.0.1:18788",
    "api_token": "worker-api-token",
    "service_name": "enoch-control-plane",
    "project_root": "/srv/enoch/projects"
  },
  "gpu": {
    "api_url": "http://127.0.0.1:18789",
    "api_token": "worker-api-token",
    "ssh_host": "worker-gpu.example.internal",
    "ssh_user": "enoch",
    "service_name": "enoch-control-plane",
    "project_root": "/srv/enoch/projects",
    "log_paths": ["/var/log/enoch-control-plane.log"]
  }
}

Campos suportados por lane:

• api_url: URL base do worker-gate. Usado primeiro para /healthz, /dashboard/api, /dashboard/api/run/{run_id} e /project-status/{project_id}.
• api_token: token de portador do worker. Tratado como segredo.
• ssh_host, ssh_user, ssh_port: alvo opcional de fallback/depuração SSH.
• service_name: nome da unidade systemd para verificações de serviço e caudas de journal.
• project_root, state_dir: raízes fixas de worker usadas para verificações de disco e artefatos.
• log_paths: caminhos de log fixos do worker-gate que podem ser seguidos.

As sondas SSH executam apenas comandos de diagnóstico fixos. Elas não aceitam entrada arbitrária de shell do cliente MCP. IDs fornecidos pelo usuário são limitados a caracteres seguros de identificador de execução/projeto, a saída de log é limitada, o SSH usa modo batch e sem stdin, e a implantação recomendada é um usuário de worker somente leitura ou política de comando forçado.

Configuração do cliente MCP

Claude Desktop

{
  "mcpServers": {
    "enoch": {
      "command": "uvx",
      "args": ["enoch-mcp"],
      "env": {
        "ENOCH_API_URL": "http://localhost:8787",
        "ENOCH_API_TOKEN": "replace-with-token"
      }
    }
  }
}

Para desenvolvimento local, aponte o cliente MCP para o checkout:

{
  "mcpServers": {
    "enoch": {
      "command": "uv",
      "args": ["--directory", "/path/to/enoch-mcp", "run", "enoch-mcp"],
      "env": {
        "ENOCH_API_URL": "http://localhost:8787",
        "ENOCH_API_TOKEN": "replace-with-token"
      }
    }
  }
}

Use as configurações equivalentes de servidor stdio local para Cursor, Copilot, Windsurf ou outros clientes MCP.

Desenvolvimento

uv sync --dev
uv run pytest -q
gitleaks detect --no-git --redact

Nota de segurança pública

Este pacote é público. Os exemplos devem usar apenas placeholders e URLs locais. Não publique nomes de host privados, IPs de LAN/Tailscale, caminhos de operador ou tokens ativos.