Lens MCP Server

Servidor MCP (Model Context Protocol) para a Lens API: workflows, knowledge bases e resultados de execução. Para uso no Cursor, VSCode (KiloCode/Reasoning) e outros clientes MCP.

Ferramentas (tools)

| Tool | Descrição | |------|-----------| | list_agents | Lista agentes (opcional: filtro por nome). Use para obter IDs antes de criar um workflow. | | create_workflow | Cria um workflow: nome, tipo (sequential, parallel, conditional, team), lista ordenada de agent_ids, formatter de saída (text = markdown; json_schema, pdf, mcp, jira). Retorna resumo em markdown para o usuário decidir o que fazer (ex.: rodar com run_workflow). | | list_workflows | Lista workflows (opcional: filtro por nome). | | run_workflow | Executa um workflow por id ou nome; opção de aguardar até completar (polling). Conteúdo em markdown é devolvido quando o formatter for text. | | get_execution_result | Retorna status, output e erro de uma execução pelo execution_id. | | list_knowledge_bases | Lista bases de conhecimento (Jira, docs, etc.). | | search_knowledge_bases | Busca semântica em uma ou mais KBs; retorna trechos relevantes. | | get_execution_formatted_outputs | Outputs formatados (PDF, MCP, etc.) da execução. | | push_documents_to_lens_kb | Inclui documentos em uma base de conhecimento (chunking e embedding/RAG). |

Instalar e rodar de qualquer máquina (npm)

Com o pacote publicado no npm:

# Rodar sem instalar (baixa na hora)
npx lens-mcp-server

Ou instalar globalmente:

npm install -g lens-mcp-server
lens-mcp-server

Fluxo típico para criar e rodar um workflow (ex.: reasoning): (1) list_agents para obter os UUIDs dos agentes; (2) create_workflow com nome (ex. "Reasoning"), tipo sequential, e a lista ordenada de agent_ids; (3) o retorno é um resumo em markdown com o workflow_id; (4) use run_workflow com esse id ou nome para executar; o conteúdo em markdown é devolvido ao usuário (formatter text).

Variáveis de ambiente obrigatórias: LENS_API_BASE_URL, LENS_API_TOKEN, LENS_ORG_ID.

| Variável | Obrigatório | Descrição | |----------|-------------|-----------| | LENS_API_BASE_URL | Sim | URL base da Lens API (ex.: http://localhost:8000). | | LENS_API_TOKEN | Sim | Bearer token para autenticação na API. | | LENS_ORG_ID | Sim | ID da organização (header X-Organization-ID). | | LENS_MCP_POLL_TIMEOUT_SEC | Não | Timeout ao aguardar conclusão do workflow (default: 120). | | LENS_MCP_POLL_INTERVAL_SEC | Não | Intervalo de polling em segundos (default: 2). |

Publicar no npm (mantenedores)

1. Ter conta no npmjs.com e estar logado (npm login).
2. Na pasta mcp-server:

npm install
npm publish

Para novas versões: altere version no package.json e rode npm publish de novo.

Requisitos

• Node.js >= 18
• Variáveis de ambiente: LENS_API_BASE_URL, LENS_API_TOKEN, LENS_ORG_ID

Build

cd mcp-server
npm install
npx tsc          # compila src/ -> dist/ (se alterou TypeScript)
npm run start   # ou: node dist/index.js

Como testar o MCP server

Pré-requisitos

1. Lens API rodando (ex.: uvicorn app.main:app --reload na raiz do ac.lens.service).
2. Token e organização: use o mesmo token que o app usa (ex.: token do Keycloak ou INTEGRATION_GATEWAY_TOKEN do .env da API) e um organization_id válido.

1. Teste rápido (subir o processo)

O server usa stdio (entrada/saída padrão); logs vão para stderr. Se subir sem cliente, fica esperando entrada.

cd mcp-server
export LENS_API_BASE_URL="http://localhost:8000"
export LENS_API_TOKEN="<seu-token>"
export LENS_ORG_ID="<sua-org-id>"

node dist/index.js
# Deve aparecer no stderr: [lens-mcp] Lens MCP server running on stdio
# O processo fica aberto; Ctrl+C para encerrar.

Se faltar LENS_API_TOKEN ou LENS_ORG_ID, ao chamar qualquer tool o server responde com erro pedindo essas variáveis.

Se aparecer TypeError: fetch failed (ou "Lens API unreachable"): a requisição à Lens API falhou — confira se a API está rodando em LENS_API_BASE_URL (ex.: uvicorn app.main:app --reload na raiz do projeto) e se a URL está correta.

2. Teste listando as tools (script)

Na pasta mcp-server, com as variáveis de ambiente já definidas:

./scripts/test-mcp-list-tools.sh
# ou
node scripts/test-mcp-list-tools.mjs

O script inicia o server, envia o handshake MCP (initialize + tools/list), imprime as tools no stdout e encerra. Exemplo de saída:

Tools registradas: 7
 - list_agents
 - list_workflows
 - create_workflow
 - run_workflow
 - get_execution_result
 - list_knowledge_bases
 - search_knowledge_bases

3. Teste chamando uma tool (list_agents)

Com o server rodando em um terminal, em outro você pode usar um cliente MCP (ex.: Cursor) ou o script de call:

./scripts/test-mcp-call-tool.sh list_agents
# ou
node scripts/test-mcp-call-tool.mjs list_agents

Isso envia initialize + tools/call com list_agents e mostra a resposta (lista de agentes da API, se o token/org estiverem corretos).

4. Teste no Cursor / VSCode

1. Configure o MCP no Cursor (Settings → MCP ou arquivo de config do MCP).
2. Adicione o servidor Lens com command, args e env (ver seção “Cursor / cliente MCP” abaixo).
3. Abra um chat e peça, por exemplo: “Liste os agentes do Lens” ou “Liste os workflows”.
4. O Cursor vai chamar list_agents ou list_workflows e mostrar o retorno.

Assim você valida o end-to-end: Cursor → MCP server → Lens API.

Distribuição

Opção 1: Tarball (npm pack)

Gera um pacote .tgz para instalar em outra máquina ou publicar em registry privado:

cd mcp-server
npm install --omit=dev
npm run pack:tgz
# Gera: lens-mcp-server-<version>.tgz

Uso do tarball em outro projeto ou máquina:

npm install /caminho/para/lens-mcp-server-1.1.1.tgz
# Ou global: npm install -g /caminho/para/lens-mcp-server-1.1.1.tgz
npx lens-mcp-server

Opção 2: Cursor / cliente MCP

No Cursor, configure o MCP para rodar o servidor por stdio. Exemplo com npx (qualquer máquina, sem instalar):

{
  "mcpServers": {
    "lens": {
      "command": "npx",
      "args": ["--yes", "lens-mcp-server"],
      "env": {
        "LENS_API_BASE_URL": "https://sua-lens-api.example.com",
        "LENS_API_TOKEN": "<seu-token>",
        "LENS_ORG_ID": "<org-id>"
      }
    }
  }
}

Ou após npm install -g lens-mcp-server:

{
  "mcpServers": {
    "lens": {
      "command": "lens-mcp-server",
      "env": {
        "LENS_API_BASE_URL": "https://sua-lens-api.example.com",
        "LENS_API_TOKEN": "<seu-token>",
        "LENS_ORG_ID": "<org-id>"
      }
    }
  }
}

Opção 3: Publicar em registry npm privado

Se a equipe usa npm privado (Azure Artifacts, Verdaccio, etc.):

1. Ajuste package.json (nome e versão) conforme o registry.
2. npm publish --access restricted (ou conforme o registry).

Desenvolvimento

• Node: >= 18
• Dependências: @modelcontextprotocol/sdk, zod

O servidor usa stdio para o protocolo MCP; logs vão para stderr.