MCP, REST e o Agente integrado

O Eidograph oferece três caminhos para agentes, todos a terminar na mesma superfície de ferramentas:

Caminho	Melhor para	Disponível em
Agente integrado	Alterações em linguagem natural ao projeto atual	Aplicações Windows e Android
MCP Streamable HTTP	Plataformas de agentes com suporte para MCP remoto por HTTP	Aplicação Windows
API REST JSON	Scripts, fluxos de trabalho e agentes personalizados	Aplicação Windows

Antes de uma ferramenta alterar um script, o Eidograph compila o candidato. Uma edição com erros do compilador ou um aviso de comando ignorado é rejeitada e o script atual não muda. As edições bem-sucedidas persistem, redesenham e entram de imediato no histórico normal de anular.

Ativar o servidor nativo

1. Na aplicação instalada, abra Definições › Servidor MCP / REST.
2. Ative o servidor e confirme que o seu estado é "em execução". A porta predefinida é 14159.
3. Ative apenas as ferramentas de que o cliente precisa.
4. Em Figuras, inspecione o ponto de exposição junto de cada figura. Um ponto preenchido significa que os clientes externos podem aceder-lhe.
5. Mantenha a ligação predefinida ao dispositivo local (loopback), a menos que esteja numa rede de confiança.

Pontos finais predefinidos:

MCP   http://127.0.0.1:14159/mcp
REST  http://127.0.0.1:14159/api/v1

DANGER

O modo LAN liga-se a 0.0.0.0 e não tem retransmissão pela internet. Os clientes nativos nessa rede podem invocar as ferramentas que ativou, por isso ative um token de acesso antes de ligar o modo LAN, use-o apenas numa rede de confiança e desligue-o depois.

Exigir um token de acesso

O servidor não exige autenticação por predefinição, o que é suficientemente seguro enquanto fica em loopback: só os programas já em execução neste PC lhe conseguem chegar. Ligue Definições › Servidor MCP / REST › Exigir um token de acesso — sempre antes de ativar o modo LAN — e o Eidograph gera um segredo que todos os pedidos têm de transportar:

Authorization: Bearer <token>

Os pedidos sem esse cabeçalho recebem 401. As definições mostram o token com um botão de cópia, Substituir o token rota-o e desligar o interruptor apaga-o. Ambos têm efeito imediato, por isso atualize todos os clientes que tenha configurado.

Encontrar o servidor a partir de outro programa

A porta é uma definição, pelo que nada fora da aplicação a pode presumir. Enquanto o servidor está a escutar, o Eidograph publica um ficheiro de descoberta e apaga-o quando o servidor para ou a aplicação termina:

Plataforma	Caminho
Windows	%LOCALAPPDATA%\eidograph.metaphor.projects\server.json
macOS	~/Library/Application Support/eidograph.metaphor.projects/server.json
Linux	$XDG_DATA_HOME/eidograph.metaphor.projects/server.json

{
  "version": "0.2.19",
  "pid": 24680,
  "updatedAt": 1757000000000,
  "bindAddress": "127.0.0.1",
  "port": 14159,
  "mcp": "http://127.0.0.1:14159/mcp",
  "api": "http://127.0.0.1:14159/api/v1",
  "token": "3f9c…",
  "lanAddresses": []
}

Leia mcp ou api e envie token como token bearer; é null quando não é exigido nenhum. Os URL publicados mantêm-se em loopback mesmo no modo LAN, porque quem lê este ficheiro está na mesma máquina. Definições › Servidor MCP / REST mostra e copia o caminho exato. Trate a ausência do ficheiro como «o servidor não está a correr», em vez de recorrer a uma porta adivinhada.

Claude Desktop

O Claude Desktop instala servidores MCP como processos stdio locais, pelo que não aceita um URL HTTP colado. Instale a extensão eidograph-mcpb para fazer a ponte — não precisa de configuração, encontra sozinha a porta e o token de acesso, e relê-os em cada pedido. Veja Claude Desktop para a instalação passo a passo com capturas de ecrã, e como a apontar para um Eidograph a correr noutro dispositivo.

Ligar uma plataforma MCP

Para um cliente que suporte Streamable HTTP — incluindo a configuração Trae / WorkBuddy copiada pela aplicação — adicione este servidor:

{
  "mcpServers": {
    "Eidograph": {
      "url": "http://127.0.0.1:14159/mcp",
      "transport": "streamable-http",
      "disabled": false
    }
  }
}

As plataformas diferem na localização do ficheiro de configuração e no esquema exterior, mas os valores essenciais são o nome do servidor, o URL e o transporte Streamable HTTP. Se uma plataforma só suportar um processo MCP local por stdio, não coloque este URL no seu campo command; use um conector HTTP ou uma ponte suportada por essa plataforma.

Depois de ligar, deixe o cliente descobrir as ferramentas e, em seguida, ler o script atual ou o registo de comandos. Uma sequência de agente fiável é:

1. list_figures para confirmar o alvo;
2. get_script e list_objects para compreender a figura atual;
3. list_commands para inspecionar a sintaxe válida do dialeto 2D/3D ativo;
4. append_commands para alterações aditivas, e set_script apenas quando linhas existentes têm de ser reescritas;
5. list_diagnostics para verificar o resultado e corrigir qualquer problema.

Chamar a API REST

Verifique primeiro o estado e a descoberta de ferramentas:

curl http://127.0.0.1:14159/api/v1/status
curl http://127.0.0.1:14159/api/v1/tools

Criar dois pontos e um segmento:

curl -X POST http://127.0.0.1:14159/api/v1/tools/append_commands \
  -H "Content-Type: application/json" \
  -H "X-Eidograph-Client: my-agent" \
  -d '{"commands":"point A -2 0\npoint B 2 0\nsegment s A B"}'

As respostas usam um único envelope: {"ok":true,"result":...} em caso de sucesso ou {"ok":false,"error":...} em caso de falha. O cabeçalho opcional X-Eidograph-Client dá ao autor da chamada um nome legível na atividade de Definições.

A superfície atual consegue ler e listar figuras, criar figuras, acrescentar ou substituir scripts, listar objetos/diagnósticos/comandos, selecionar um objeto na tela e exportar uma figura exposta como SVG, PNG, GIF ou MP4. As permissões de ferramentas e a exposição de figuras são aplicadas em cada chamada.

Configurar o Agente integrado

Guarde vários modelos em Definições › Agente e depois alterne entre eles a partir do cabeçalho do Agente. O Eidograph suporta três famílias de protocolo:

• pontos finais Chat Completions compatíveis com OpenAI;
• Anthropic Messages;
• Google Gemini / Vertex generateContent.

Cada modelo guardado tem um nome de exibição, fornecedor, URL base, chave de API e ID de modelo. Pode introduzir um ID manualmente se a descoberta de modelos falhar. Pontos finais locais como o Ollama e o LM Studio também podem funcionar, mas o ponto final tem de permitir pedidos de origem cruzada a partir da WebView da aplicação (CORS).

O Agente integrado aceita imagens anexadas ou coladas, o que é útil para transformar uma fotografia de manual escolar ou um esboço numa construção. O suporte de visão depende do ponto final do modelo; um pedido não suportado aparece como erro na conversa.

Permissões e limites de dados

• O Agente integrado e os agentes externos não têm nenhum caminho privilegiado oculto; ambos usam as mesmas definições de ferramentas.
• As edições externas visam o projeto ativo e respeitam o estado de exposição de cada figura.
• As chaves de API nunca são escritas no .eido. As aplicações Windows e Android usam armazenamento de credenciais protegido pelo sistema operativo.
• As conversas do Agente ficam excluídas do .eido por predefinição e só são partilhadas quando Incluir conversas do agente é ativado explicitamente.