mikrus-mcp

Servidor MCP (Model Context Protocol) para gerenciar servidores VPS via API mikr.us e servidores Linux remotos via SSH. Construído em Python, executa em qualquer lugar — localmente, no Docker ou como integração com Claude Desktop.

GitHub

Experimente este MCPPatrocinado

Documentação

Servidor MCP Mikrus

Um servidor Model Context Protocol endurecido para gerenciar instâncias VPS mikr.us e hosts Linux remotos via SSH.

mikrus-mcp expõe um conjunto limitado de capacidades de administração por meio de um caminho de invocação único com aplicação de políticas. Ele suporta stdio local e Streamable HTTP autenticado somente em loopback, separa operações de leitura de mutações, vincula ações privilegiadas a uma identidade e recurso de destino exatos e mantém a execução bruta de shell fora da superfície pública do MCP.

A versão 2.1 adiciona execução de programas SSH tipados e jobs de processo limitados. A versão 2.0 permanece intencionalmente mais estrita que a 1.x: Python 3.12+ é obrigatório, HTTP+SSE legado foi removido, a verificação de host SSH está habilitada por padrão, mutações exigem habilitação explícita de escrita e aprovações de curta duração no lado do servidor, e ferramentas de gerenciamento legadas amplas foram substituídas por capacidades específicas de operação.

Destaques

mikr.us + SSH — gerencie alvos da API mikr.us e hosts Linux comuns acessíveis via SSH a partir do mesmo servidor MCP.
Um núcleo de invocação — validação, autorização, vínculo de destino, aprovações, prazos, concorrência, sanitização, proveniência e classificação de falhas são aplicados em um único caminho de propriedade da aplicação.
Autorização em duas fases — verificações de seletor e política de dados ocorrem antes da resolução do destino; verificações exatas de identidade e recurso do backend ocorrem após a resolução.
Mutações seguras por padrão — gravações são desabilitadas por padrão, nunca repetidas automaticamente e exigem uma aprovação única vinculada a principal, capacidade, identidade de destino resolvida, recurso e argumentos normalizados.
Identidade SSH verificada — a verificação de chave de host está habilitada por padrão; a identidade de mutação inclui a impressão digital SHA-256 da chave de host verificada.
Sem ferramenta pública de shell bruto — operações privilegiadas são expostas como ferramentas limitadas e específicas de operação com validação.
Builds reproduzíveis — bloqueios de dependência com hash confirmados são mantidos para Linux x64 em CPython 3.12, 3.13 e 3.14.
Verificação exata de artefato — CI compila e exercita o wheel exato e o artefato de contêiner Linux/amd64.
Proveniência de runtime — descoberta de capacidades e resultados bem-sucedidos expõem versão, origem/build, artefato, configuração e campos de geração de instância quando fornecidos pelo perfil de build/implantação.
Autoridade de padrões fixada — contratos de repositório estão alinhados com a revisão estável ai-skills@main fixada registrada em ai-skills.lock.yaml.

Requisitos

Para execução local:

Python 3.12, 3.13 ou 3.14
uma chave de API mikr.us e identificador de servidor, ou um host Linux acessível via SSH
para gravações SSH: uma chave de host verificada e um destino com os primitivos POSIX/Python necessários

Docker pode ser usado em vez de instalar Python diretamente.

Início rápido

1. Clone e crie um ambiente

git clone https://github.com/paulomac1000/mikrus-mcp.git
cd mikrus-mcp

python3.12 -m venv .venv
.venv/bin/python -m pip install --upgrade pip
.venv/bin/python -m pip install .

Para desenvolvimento de repositório, use o bloqueio de desenvolvimento com hash confirmado em vez de resolver dependências ad hoc. Consulte Desenvolvimento.

2. Configure um único servidor mikr.us

export MIKRUS_API_KEY='replace-me'
export MIKRUS_SERVER_NAME='srv123'

A forma de servidor único é a configuração mais simples. Para SSH ou múltiplos alvos, use MCP_SERVERS; exemplos estão abaixo.

3. Inicie o servidor MCP

.venv/bin/python -m mikrus_mcp

stdio é o transporte padrão, portanto este comando é adequado para clientes MCP de desktop que iniciam o servidor como subprocesso.

4. Compile e execute com Docker

docker build -t mikrus-mcp:2.1.0 .

docker run --rm \
  -e MIKRUS_API_KEY='replace-me' \
  -e MIKRUS_SERVER_NAME='srv123' \
  mikrus-mcp:2.1.0

Imagens de release publicadas são promovidas por digest imutável. Prefira uma tag de release ou digest em vez de uma tag móvel não fixada em produção.

Configuração do cliente MCP

Uma configuração típica de cliente de desktop pode iniciar o projeto diretamente via Python:

{
  "mcpServers": {
    "mikrus": {
      "command": "/absolute/path/to/mikrus-mcp/.venv/bin/python",
      "args": ["-m", "mikrus_mcp"],
      "env": {
        "MIKRUS_API_KEY": "replace-me",
        "MIKRUS_SERVER_NAME": "srv123"
      }
    }
  }
}

Use caminhos absolutos. Aplicações GUI frequentemente iniciam com um diretório de trabalho diferente do seu shell.

Para clientes baseados em Docker, aponte o comando MCP para docker run e passe credenciais por meio de um arquivo de ambiente ou mecanismo secreto, em vez de incorporar credenciais de longa duração na configuração do cliente.

Ferramentas disponíveis

O catálogo suportado é sensível à configuração. Ferramentas que não se aplicam a nenhum backend configurado, não possuem o armazenamento de jobs duráveis ou são mutações desabilitadas por política são omitidas da lista pública de ferramentas e permanecem visíveis no catálogo de capacidades com um motivo de inatividade.

Descoberta

Ferramenta	Tipo	Descrição
`list_configured_servers`	Leitura	Lista alvos configurados e seu estado de conexão atual.
`describe_mikrus_capabilities`	Leitura	Retorna o catálogo de capacidades suportadas e metadados de política.

Ferramentas da API mikr.us

Estas capacidades exigem pelo menos um alvo mikrus configurado.

Ferramenta	Tipo	Descrição
`get_server_info`	Leitura	Informações básicas do VPS, como RAM, disco, expiração e estado do servidor.
`list_servers`	Leitura	Lista servidores associados à conta mikr.us.
`get_server_stats`	Leitura	Recupera estatísticas de recursos e runtime.
`restart_server`	Mutação	Reinicia o VPS selecionado.
`get_logs`	Leitura	Busca logs recentes de tarefas mikr.us.
`get_log_by_id`	Leitura	Busca um log de tarefa por ID.
`boost_server`	Mutação	Solicita o aumento temporário de recursos suportado.
`get_db_info`	Leitura sensível	Recupera informações de conexão do banco de dados; campos de credenciais são protegidos pelo sanitizador de resposta.
`get_ports`	Leitura	Mostra portas atribuídas.
`get_cloud`	Leitura	Mostra serviços em nuvem associados à conta.
`assign_domain`	Mutação	Atribui um domínio ou subdomínio gerado a uma porta.

Ferramentas do sistema Linux

Estas capacidades operam por meio da abstração de backend configurada e estão disponíveis onde o destino as suporta.

Ferramenta	Tipo	Descrição
`read_file`	Leitura sensível	Lê um arquivo de texto limitado de um caminho permitido.
`write_file`	Mutação	Grava um arquivo atomicamente usando travessia de diretório sem seguir links.
`get_service_status`	Leitura	Inspeciona um serviço systemd.
`change_service_state`	Mutação	Inicia, para, reinicia, habilita ou desabilita um serviço validado.
`analyze_disk`	Leitura	Inspeciona o uso do sistema de arquivos.
`check_port`	Leitura	Verifica se uma porta TCP está escutando e identifica o processo proprietário quando disponível.
`list_processes`	Leitura sensível	Lista processos usando um contrato de saída limitado.
`terminate_process`	Mutação	Encerra um alvo de processo validado.
`update_system`	Mutação	Executa o fluxo de atualização do sistema suportado.
`list_directory`	Leitura sensível	Lista um diretório validado.
`tail_file`	Leitura sensível	Lê o final limitado de um arquivo de texto.
`search_in_files`	Leitura sensível	Pesquisa dentro de um caminho validado.
`execute_program`	Mutação	Executa um executável aprovado com `argv` tipados, `cwd` opcionais e stdin opcional por meio de um alvo SSH.
`start_program`	Mutação	Inicia um programa tipado aprovado e retorna um identificador de job em processo limitado.
`get_program_status`	Leitura	Inspeciona o status de um job de programa tipado de propriedade do usuário.
`get_program_result`	Leitura	Recupera o resultado terminal de um job de programa tipado de propriedade do usuário.
`cancel_program`	Mutação	Cancela um job de programa tipado enfileirado ou em execução de propriedade do usuário.
`remote_job_start`	Mutação	Inicia um job durável com suporte SSH usando uma chave de idempotência.
`remote_job_status`	Leitura	Inspeciona um job remoto durável por ID de job vinculado ao proprietário.
`remote_job_wait`	Leitura	Aguarda no lado do servidor por progresso limitado de job remoto ou estado terminal.
`remote_job_result`	Leitura	Recupera o resultado de um job remoto durável.
`remote_job_output`	Leitura	Lê stdout ou stderr limitados usando um cursor explícito.
`remote_job_cancel`	Mutação	Cancela o grupo de processos remoto exato após validação de identidade PID e relata se o encerramento foi verificado.
`file_patch_atomic`	Mutação	Substitui um arquivo regular somente quando seu digest SHA-256 atual corresponde a `expected_digest` (compare-and-swap; seguro para binários via base64; serializado por um bloqueio consultivo local do host entre escritores mikrus-mcp).
`cron_list`	Leitura	Relata perfis cron de propriedade do usuário com seu estado de crontab instalado e digest de marcador.
`cron_upsert`	Mutação	Projeta idempotentemente um perfil cron de propriedade do usuário no crontab instalado.
`cron_remove`	Mutação	Remove exatamente o marcador e o par de linhas gerado para um perfil cron de propriedade do usuário.
`docker_runtime_snapshot`	Leitura sensível	Retorna um instantâneo semântico limitado de um serviço ou contêiner compose.
`docker_recreate_plan`	Leitura sensível	Calcula um plano de recriação semântico canônico com um recibo de plano limitado e um registro expirante no lado do servidor.
`docker_recreate_apply`	Mutação	Aplica um plano de recriação verificado; relata `ALREADY_APPLIED` quando o estado já corresponde.
`service_wait`	Leitura	Aguarda no lado do servidor pela prontidão limitada do serviço compose.
`get_memory_info`	Leitura	Mostra o uso de memória.
`get_network_info`	Leitura sensível	Mostra interfaces de rede e sockets em escuta.
`get_process_tree`	Leitura sensível	Mostra a árvore de processos.

Ferramentas Docker

Ferramenta	Tipo	Descrição
`list_docker_containers`	Leitura sensível	Lista contêineres e estado atual.
`get_docker_logs`	Leitura sensível	Busca logs recentes limitados de um contêiner.
`get_docker_stats`	Leitura	Mostra estatísticas de recursos do contêiner.

Ferramentas de journal

Ferramenta	Tipo	Descrição
`get_journal_logs`	Leitura sensível	Busca saída de journal limitada para uma unidade.
`find_system_errors`	Leitura sensível	Encontra eventos recentes de journal de nível de erro.
`search_journal_logs`	Leitura sensível	Pesquisa a saída do journal por um termo limitado.

O acesso ao journal depende das permissões da conta remota. Um sudo_password configurado pode ser usado quando a conta ainda não tem permissão para ler o journal; a senha é enviada pelo stdin do processo em vez de interpolada no comando do shell.

Configuração de múltiplos servidores

Defina MCP_SERVERS como um objeto JSON chaveado pelo alias público do destino.

Exemplo misto mikr.us + SSH

export MCP_SERVERS='{
  "vps": {
    "type": "mikrus",
    "key": "replace-me",
    "srv": "srv123"
  },
  "host": {
    "type": "ssh",
    "host": "server.example.com",
    "port": 22,
    "user": "admin",
    "ssh_key": "/home/me/.ssh/id_ed25519",
    "known_hosts_file": "/home/me/.ssh/known_hosts"
  }
}'
export MCP_DEFAULT_SERVER='vps'

Campos do destino SSH

Campo	Obrigatório	Padrão	Notas
`type`	sim	—	Deve ser `"ssh"`.
`host`	sim	—	Nome do host ou endereço IP.
`port`	não	`22`	Porta TCP, 1–65535.
`user`	não	`root`	Usuário SSH.
`password`	não	—	Autenticação por senha. Prefira autenticação por chave quando possível.
`ssh_key`	não	—	Arquivo de chave privada existente; deve estar protegido contra acesso de grupo/outros.
`ssh_cert`	não	—	Certificado SSH opcional.
`sudo_password`	não	—	Senha opcional para comandos `sudo -S` específicos de operação.
`known_hosts_file`	não	Política padrão do AsyncSSH	Arquivo `known_hosts` explícito opcional.
`timeout`	não	`30`	Entrada de timeout de conexão/operação, 1–300 segundos.
`verify_host_key`	não	`true`	A verificação de chave de host está habilitada por padrão.
Disabling SSH host verification requires `MCP_ALLOW_INSECURE_SSH=1` e é limitado ao uso de desenvolvimento somente leitura. A inicialização falha se gravações estiverem habilitadas enquanto um alvo SSH tiver a verificação de host desabilitada.

Trabalhos remotos duráveis

Defina um caminho absoluto de armazenamento controlado pelo operador para ativar a família de capacidades remote_job_*. O arquivo é criado com permissões privadas e atualizado por meio de substituição atômica limitada:

export MCP_REMOTE_JOB_STORE_FILE="$PWD/.mikrus-remote-jobs.json"

A capacidade permanece inativa quando essa configuração está ausente ou quando nenhum alvo SSH está configurado. Não coloque o armazenamento em um diretório compartilhado ou com links simbólicos. O cancelamento verifica o término dos processos descendentes após o kill e relata um campo terminated honesto; uma inicialização cujo resultado era ambíguo é reconciliada uma vez contra o registro remoto em vez de exibir o timeout bruto (uma consulta irrecuperável exibe AMBIGUOUS_OUTCOME). Os registros de trabalho expiram após um horizonte de retenção de 7 dias (REMOTE_JOB_RETENTION_SECONDS = 604800); registros expirados são limpos na próxima leitura do registro.

Perfis Cron

Defina um caminho absoluto de armazenamento controlado pelo operador para ativar a família de capacidades cron_list, cron_upsert e cron_remove:

export MCP_CRON_PROFILE_STORE_FILE="$PWD/.mikrus-cron-profiles.json"
export MCP_DOCKER_PLAN_STORE_FILE="$PWD/.mikrus-docker-plans.json"

Os perfis são registros duráveis vinculados ao proprietário com uma agenda tipada de cinco campos, um executável na lista de permissões, argumentos tipados e atribuições de ambiente limitadas opcionais. A projeção no crontab instalado usa uma linha de comentário marcadora (# mikrus-mcp:<profile_id>:sha256=<digest>) seguida por exatamente uma linha cron gerada cujos argumentos são estritamente escapados com aspas simples; strings de comando arbitrárias nunca são serializadas. As atualizações do crontab relêem o arquivo imediatamente antes da instalação e falham com CONCURRENT_MODIFICATION quando ele mudou concorrentemente. Todas as linhas do crontab que não são de perfil são preservadas byte a byte, e as capacidades cron permanecem inativas quando a configuração está ausente ou nenhum alvo SSH está configurado. Instalações e leituras do crontab são serializadas por meio de um bloqueio consultivo local ao host (~/.mikrus-mcp/locks/crontab.lock) para que os gravadores mikrus-mcp nunca se intercalem; gravadores concorrentes não-mikrus ficam fora dessa garantia e ainda são detectados pela releitura imediata pré-instalação (CONCURRENT_MODIFICATION).

A mesma família de bloqueios consultivos (~/.mikrus-mcp/locks/cas.lock) cobre file_patch_atomic: a leitura do digest, a comparação, a gravação do arquivo temporário e a renomeação mantêm o bloqueio, tornando a comparação-e-troca atômica entre todos os gravadores mikrus-mcp no host. Gravadores não-mikrus ficam fora da garantia; a pré-condição do digest ainda os detecta no início da operação.

Docker e Compose

As capacidades docker_runtime_snapshot, docker_recreate_plan, docker_recreate_apply e service_wait gerenciam serviços compose por meio de um alvo SSH sem shell. docker_recreate_plan resolve a identidade do projeto compose a partir dos rótulos dos contêineres ativos (nunca o nome base do diretório), lê o estado desejado por meio de docker compose config e retorna um plano semântico canônico limitado por um recibo plan:v1:sha256:.... O plano persiste em um armazenamento de registros durável no lado do servidor (habilitado por MCP_DOCKER_PLAN_STORE_FILE, um caminho absoluto controlado pelo operador com permissões privadas; os registros expiram após 300 segundos), então o apply deriva cada entrada de estado desejado do registro armazenado em vez dos argumentos de invocação. Os valores de ambiente são usados para comparação no apply, mas nunca são retornados ao modelo — apenas as chaves de ambiente são visíveis.

docker_recreate_plan adicionalmente registra se o contêiner ativo carrega desvio somente em tempo de execução em relação ao compose (campos como ambiente aplicado em tempo de execução ou rótulos que o arquivo compose não declara). O planejamento com allow_runtime_drift=true registra aceitação explícita; caso contrário, docker_recreate_apply recusa a mutação com RECREATE_CONFIG_DRIFT e o operador deve replanejar para aceitar a perda dessa configuração somente em tempo de execução.

docker_recreate_apply recebe apenas o serviço e plan_receipt; um registro ausente ou expirado é PLAN_STALE. O registro armazenado classifica o desvio: campos desejados pelo compose alterados desde o planejamento → PLAN_STALE; o digest da imagem mudou em uma tag implicitamente fixada → IMAGE_DRIFT; o digest mudou sob uma imagem explicitamente fixada → PLAN_STALE. O comportamento é idêntico com falha fechada: replanejamento necessário. Quando o estado semântico ativo já é igual ao estado desejado pelo compose, o apply relata ALREADY_APPLIED sem recriar. O apply em si é a sequência argv limitada docker compose -p <project> -f <files>... up -d --no-deps --force-recreate <service>; uma única verificação de inspeção segue, e uma espera de prontidão é obrigatória: o padrão é healthy quando o contêiner recriado define um healthcheck e running caso contrário, com um orçamento de 15 segundos; readiness e timeout_seconds (5–25) são apenas de ajuste. Uma espera falha exibe seu erro tipado com applied=true na mensagem — a recriação foi executada, então reconcilie em vez de tentar novamente às cegas. service_wait consulta docker inspect dentro de uma única invocação auxiliar limitada e relata READINESS_TIMEOUT ou HEALTH_FAILED como erros de classe de leitura; com um plan_receipt ele verifica se o registro existe antes de esperar.

Campos de alvo mikr.us

Campo	Obrigatório	Padrão	Notas
`type`	sim	—	Deve ser `"mikrus"`.
`key`	sim	—	Chave de API.
`srv`	sim	—	ID estável do servidor mikr.us.
`api_url`	não	`https://api.mikr.us`	Deve usar HTTPS.

Se MCP_DEFAULT_SERVER for omitido, o primeiro alvo configurado é usado como seletor padrão.

Autorização e aprovações

Modelo de escopo

O padrão integrado de operador único inclui estes eixos de política de leitura:

tool:*
target:*
target-id:*
resource:*
data:*

Mutações adicionalmente exigem seu escopo de capacidade e write:server.

Se você definir MCP_ALLOWED_SCOPES você mesmo, ele substitui o conjunto padrão. Uma substituição legada tool:*,target:* é portanto intencionalmente insuficiente para operações com suporte a alvo após a fase de autorização de identidade resolvida.

As famílias de escopo importantes são:

tool:<capability> — permite a própria capacidade.
target:<selector> — permite o alias público de alvo configurado antes da resolução do alvo.
target-id:<resolved-identity> — permite a identidade exata do backend resolvido.
resource:<capability>:sha256:<digest> — permite um recurso normalizado exato; resource:* é o perfil curinga explícito.
data:<classification> — permite a classe de confidencialidade do manifesto; data:* é o perfil curinga explícito.
write:server — habilita a autorização de mutação quando a política de gravação do processo também está habilitada.

Habilitando mutações

Mutações exigem tanto a política de processo quanto um registro de aprovação de curta duração correspondente:

export MCP_WRITE_ENABLED=true
export MCP_APPROVAL_FILE="$PWD/.mikrus-approvals.json"

Os registros de aprovação são criados a partir do shell confiável do operador, não pelo modelo. O auxiliar resolve o alvo antes de persistir o registro; para SSH, isso vincula a impressão digital verificada atual da chave do host.

Forma geral:

.venv/bin/python scripts/approval.py \
  --file "$MCP_APPROVAL_FILE" \
  --capability '<capability>' \
  --principal '<principal>' \
  --server '<configured-alias>' \
  --resource '<normalized-resource>' \
  --arguments-json '<JSON object without server>' \
  --ttl-seconds 60

As aprovações expiram rapidamente (padrão de 60 segundos, máximo de 300 segundos), são consumidas uma vez e são correspondidas contra principal, capacidade, identidade exata do alvo resolvido, recurso e digest de argumento normalizado.

Transportes

stdio

stdio é o transporte padrão e recomendado para integrações locais de desktop:

export MCP_TRANSPORT=stdio
.venv/bin/python -m mikrus_mcp

O tráfego do protocolo é dono do stdout; diagnósticos são gravados no stderr.

HTTP Streamable

O HTTP Streamable é deliberadamente restrito a endereços de loopback literais e exige um arquivo de token portador protegido.

umask 077
python -c 'import secrets; print(secrets.token_urlsafe(48))' > .mcp-http-token
chmod 600 .mcp-http-token

export MCP_TRANSPORT=streamable-http
export MCP_HOST=127.0.0.1
export MCP_PORT=8000
export MCP_HTTP_BEARER_TOKEN_FILE="$PWD/.mcp-http-token"

.venv/bin/python -m mikrus_mcp

Os clientes se conectam a http://127.0.0.1:8000/mcp com Authorization: Bearer <token>.

A exposição HTTP remota/pública não faz parte do perfil de segurança suportado. A ponte legada HTTP+SSE de dois endpoints e a ponte REST não autenticada foram removidas na versão 2.0.

Formato de resultado

Os resultados da aplicação usam um envelope estruturado de sucesso/erro e incluem metadados de correlação/proveniência.

Sucesso representativo:

{
  "success": true,
  "data": {
    "param_ram": "1024"
  },
  "_meta": {
    "request_id": "6a5c...",
    "capability": "get_server_info",
    "capability_version": "2.1.0",
    "source": "mikrus-mcp",
    "artifact": "mikrus-mcp==2.1.0",
    "target": "srv123",
    "target_identity": "mikrus:srv123",
    "backend": "mikrus",
    "duration_ms": 42
  }
}

Falha representativa:

{
  "success": false,
  "error": {
    "code": "RATE_LIMITED",
    "message": "request rate limit exceeded",
    "retryable": true,
    "retry_after_seconds": 2.0
  },
  "_meta": {
    "request_id": "9b8f...",
    "capability": "get_server_info",
    "source": "mikrus-mcp"
  }
}

Os metadados são incluídos apenas quando são seguros e realmente conhecidos. Por exemplo, uma falha de autorização pré-resolução não divulga a identidade resolvida do backend.

Os perfis de build e implantação fornecem proveniência imutável por meio do carimbo _build_provenance.json embutido, gravado por scripts/stamp_build_provenance.py a partir das entradas --source-revision, --build-id, --built-at e --config-revision; packageContentDigest é calculado a partir do pacote carimbado durante o carimbo. Em tempo de execução, apenas duas variáveis de ambiente são lidas: MIKRUS_MCP_CONFIG_REVISION (substitui o configRevision carimbado) e MIKRUS_MCP_DEPLOYMENT_RECEIPT_FILE (caminho do recibo de implantação). Os sourceRevision, buildId, packageContentDigest e builtAt carimbados são relatados na descoberta de capacidades e nos metadados de resultado bem-sucedido; eles não podem ser injetados por meio de variáveis de ambiente ou inferidos de um checkout montado. O build roda por meio de scripts/build_wheel.py --provenance stamped|unstamped para que o carimbo não possa ficar silenciosamente desatualizado.

Os limites de resultado são aplicados contra o envelope de aplicação serializado, incluindo metadados, em vez de apenas o valor aninhado data.

Modelo de segurança

mikrus-mcp é um serviço de administração privilegiado. Trate seu ambiente de processo, arquivo de token portador, chaves SSH, registro de aprovações e credenciais de alvo como segredos.

Trabalhos de programa tipados permanecem limitados e locais ao processo. Quando MCP_REMOTE_JOB_STORE_FILE está configurado, as ferramentas remote_job_* usam um recibo durável vinculado ao proprietário e um auxiliar JSON-stdin no lado SSH; status, espera, resultado, cursores de saída e cancelamento não exigem loops sleep no lado do modelo ou arqueologia de PID. O caminho do armazenamento deve ser um caminho de arquivo absoluto controlado pelo operador. Mutações de trabalho remoto ainda exigem habilitação de gravação e aprovação única.

Padrões principais:

sem fallback de um alvo falho para outro alvo configurado;
verificação de chave de host SSH habilitada por padrão;
HTTP Streamable autenticado somente em loopback;
mutações desabilitadas a menos que MCP_WRITE_ENABLED=true;
aprovações únicas no lado do servidor para cada mutação pública;
sem novas tentativas automáticas de mutação após timeout, desconexão, limite de taxa ou conclusão ambígua;
sem ferramenta pública de comando arbitrário;
execução de programa tipado é somente SSH, vinculada a aprovação e envia valores controlados pelo usuário como stdin do auxiliar em vez de texto de comando de shell;
gravações de arquivo remoto sem seguir links, seguras para componentes;
comportamento limitado de solicitação, resposta, saída, concorrência e prazo;
campos de resposta sensíveis sanitizados antes da serialização visível ao modelo.

Leia SECURITY.md antes de habilitar gravações ou implantar o servidor fora de um ambiente descartável.

Desenvolvimento

O repositório mantém locks de desenvolvimento Linux x64 com hash para cada linha Python suportada. Para a linha padrão 3.12:

python3.12 -m venv .venv
.venv/bin/python -m pip install "pip==26.1.2"
.venv/bin/python -m pip install --require-hashes -r requirements-dev-linux-x64-py312.lock
.venv/bin/python -m pip install --no-deps .

Execute o gate rápido sem credenciais:

.venv/bin/python scripts/core_gate.py

Execute o gate completo do repositório local:

.venv/bin/python scripts/ci.py

Execute um teste focado:

.venv/bin/python -m pytest tests/unit/test_kernel.py -q

Construa o wheel (builds carimbados recusam-se a executar quando as fontes são mais novas que o carimbo de build embutido; builds sem carimbo removem o carimbo primeiro):

.venv/bin/python scripts/build_wheel.py --provenance stamped
# or, for an unstamped local wheel:
.venv/bin/python scripts/build_wheel.py --provenance unstamped

requirements-runtime.in e requirements-dev.in são entradas editadas por humanos. Os arquivos requirements-*-linux-x64-py3*.lock são grafos hashados exatos gerados e não devem ser editados manualmente.

O CI hospedado adicionalmente valida a matriz Python suportada, manifestos, documentação, política de segurança estática, comportamento exato do wheel, transportes MCP oficiais, locks de dependência e comportamento do contêiner Linux/amd64.

Arquitetura

MCP client
   |
   |  stdio / authenticated loopback Streamable HTTP
   v
MCP registration + transport boundary
   |
   v
InvocationKernel
   |-- argument validation
   |-- principal / selector authorization
   |-- target resolution
   |-- resolved identity / resource authorization
   |-- write policy + one-time approval
   |-- deadline + concurrency policy
   |-- adapter execution
   |-- sanitization + provenance + structured errors
   |
   v
TargetRegistry
   |                    |
   v                    v
mikr.us API adapter   SSH adapter

Os adaptadores de backend não possuem a política MCP. Os wrappers de transporte não contornam o kernel. O registro público de ferramentas é derivado do catálogo de manifestos ativo de propriedade da aplicação.

Para o ciclo de vida completo e o modelo de falha, veja docs/architecture.md.

Solução de problemas

Uma ferramenta está ausente de `list_tools`

Os catálogos suportado e ativo são intencionalmente diferentes. Uma capacidade pode estar inativa porque:

nenhum backend configurado a suporta;
gravações estão desabilitadas;
outra política de processo torna a capacidade indisponível.

Inspecione describe_mikrus_capabilities / capabilities://catalog para o motivo da inatividade.

`AUTHORIZATION_FAILED` após atualizar da versão 1.x

Se você definir explicitamente MCP_ALLOWED_SCOPES, verifique se ele inclui os eixos de autorização resolvidos. O padrão da versão 2.0 é:

tool:*,target:*,target-id:*,resource:*,data:*

Mutações adicionalmente precisam do escopo de ferramenta relevante, além de write:server, habilitação de gravação de processo e uma aprovação correspondente.

SSH recusa-se a iniciar ou conectar

A verificação de host está habilitada por padrão. Certifique-se de que o host remoto esteja presente na política efetiva de known_hosts ou defina um known_hosts_file válido. Não desative a verificação para implantações graváveis.

`health://ready` relata não pronto

O destino padrão configurado é uma dependência obrigatória de prontidão. A inicialização em si é preguiçosa, então o destino pode inicialmente estar not_connected; a prontidão se torna verdadeira somente após uma conexão bem-sucedida com o destino padrão.

Mutação retorna `AMBIGUOUS_OUTCOME`

Não tente novamente às cegas. A solicitação pode ter chegado ao backend antes da falha de transporte/prazo. Reconcilie o estado remoto primeiro e, em seguida, emita uma nova aprovação somente se outra mutação for realmente necessária.

HTTP transmissível recusa o arquivo de token

O arquivo de token deve ser um arquivo regular, sem symlink, de propriedade do usuário do processo, não acessível por grupo/outros usuários, e conter um token de pelo menos 32 caracteres.

Padrões e migração

O repositório fixa a autoridade exata de AI Skills em ai-skills.lock.yaml. O contrato de arquitetura MCP é baseado no ponto de entrada estável mcp-server-architect/STANDARD.md.

O CI do repositório emite evidências estruturais contra a autoridade fixada. Evidência estrutural não é o mesmo que aceitação independente de produção; evidência de sistema real específica da implantação e revisão independente permanecem como portões separados.

Para as mudanças de quebra da versão 1.x → 2.0 e o procedimento de reversão, consulte MIGRATION.md.

Referências adicionais:

Licença

MIT