Codelogic

Utilize os dados ricos de dependência de software da Codelogic em seu assistente de programação de IA.

Documentação

lineai-mcp-server

Um MCP Server para utilizar os dados ricos de dependências de software da Lineai no seu assistente de programação com IA.

Componentes

Ferramentas

O servidor implementa oito ferramentas: duas ferramentas de impacto e seis ferramentas de grafo apoiadas pela API HTTP de grafo da Lineai.

Ferramentas de Análise de Código

lineai-method-impact: Obtém uma avaliação de impacto das APIs do servidor Lineai para o seu código.
- Recebe o "método" em que você está trabalhando e sua "classe" associada.
lineai-database-impact: Analisa impactos entre código e entidades de banco de dados.
- Recebe o tipo de entidade de banco de dados (coluna, tabela ou visão) e seu nome.

Ferramentas da API de Grafo

Estas chamam endpoints POST / GET sob /api/ai-retrieval/graph/ no mesmo host que LINEAI_SERVER_HOST, usando a mesma autenticação de sessão que outras ferramentas MCP. Se as rotas de grafo não estiverem implantadas, o servidor retorna uma mensagem clara no estilo "grafo não disponível" (frequentemente após HTTP 404).

lineai-graph-capabilities: GET — descubra tipos de relacionamento, limites e sinalizadores suportados para a visão materializada do workspace (materializedViewId padrões de LINEAI_WORKSPACE_NAME como outras ferramentas).
lineai-graph-search: Pesquise nós por texto query / q e/ou identity_prefix; opcional scan_space, limit, etc.
lineai-graph-impact: Travessia de dependência / raio de explosão a partir de seed_node_ids.
lineai-graph-path-explain: Explicação no estilo caminho mais curto entre from_node_id e to_node_id.
lineai-graph-validate-change-scope: Lista de verificação heurística / resumo de risco para uma mudança proposta, dados nós iniciais e proposed_change_summary.
lineai-graph-owners: Resolva um nó por node_id ou identity_prefix e exiba campos de propriedade cujos nomes contenham "owner".

Os argumentos das ferramentas aceitam aliases snake_case (por exemplo, materialized_view_id, seed_node_ids) quando indicado no esquema MCP; os corpos de requisição enviados à Lineai usam chaves JSON camelCase.

Instalação

Pré-requisitos

O servidor MCP depende do Astral UV para executar, por favor instale

Solução alternativa para MacOS com uvx

Há um problema conhecido com uvx no MacOS onde o servidor MCP da Lineai pode falhar ao iniciar em certos IDEs (como Cursor), resultando em erros como: Veja issue #11

Failed to connect client closed

Isso parece ser um problema com o Astral uvx rodando no MacOS. O seguinte pode ser usado como solução alternativa:

Clone este projeto localmente.
Configure seu mcp.json para usar uv em vez de uvx. Por exemplo:

{
  "mcpServers": {
    "lineai-mcp-server": {
      "type": "stdio",
      "command": "<PATH_TO_UV>/uv",
      "args": [
        "--directory",
        "<PATH_TO_THIS_REPO>/lineai-mcp-server-main",
        "run",
        "lineai-mcp-server"
      ],
      "env": {
        "LINEAI_SERVER_HOST": "<url to the server e.g. https://myco.app.lineai.net>",
        "LINEAI_USERNAME": "<my username>",
        "LINEAI_PASSWORD": "<my password>",
        "LINEAI_WORKSPACE_NAME": "<my workspace>",
        "LINEAI_DEBUG_MODE": "true"
      }
    }
  }
}

Reinicie o Cursor.
Garanta que a Regra Global do Cursor para Lineai esteja em vigor.
Abra a aba MCP no Cursor e atualize o lineai-mcp-server.
Peça ao Cursor para fazer uma alteração de código em uma classe existente. O servidor MCP agora deve executar a análise de impacto com sucesso.

Configuração para Diferentes IDEs

Configuração do Visual Studio Code

Para configurar este servidor MCP no VS Code:

Primeiro, garanta que o modo agente do GitHub Copilot esteja habilitado no VS Code.
Crie um arquivo .vscode/mcp.json no seu workspace com a seguinte configuração:

{
  "servers": {
    "lineai-mcp-server": {
      "type": "stdio",
      "command": "uvx",
      "args": [
        "lineai-mcp-server@latest"
      ],
      "env": {
        "LINEAI_SERVER_HOST": "<url to the server e.g. https://myco.app.lineai.net>",
        "LINEAI_USERNAME": "<my username>",
        "LINEAI_PASSWORD": "<my password>",
        "LINEAI_WORKSPACE_NAME": "<my workspace>",
        "LINEAI_DEBUG_MODE": "true"
      }
    }
  }
}

Nota: Em alguns sistemas, você pode precisar usar o caminho completo para o executável uvx em vez de apenas "uvx". Por exemplo: /home/user/.local/bin/uvx no Linux/Mac ou C:\Users\username\AppData\Local\astral\uvx.exe no Windows.

Alternativamente, você pode executar o comando MCP: Add Server na Paleta de Comandos e fornecer as informações do servidor.
Para gerenciar seus servidores MCP, use o comando MCP: List Servers na Paleta de Comandos.
Uma vez configurado, as ferramentas do servidor estarão disponíveis para o modo agente do Copilot. Você pode ativar/desativar ferramentas específicas conforme necessário clicando no botão Ferramentas na visualização de Chat quando estiver no modo agente.
Para usar as ferramentas da Lineai no modo agente, você pode perguntar especificamente sobre impactos de código ou relacionamentos de banco de dados, e o agente utilizará as ferramentas apropriadas.

Configuração do Claude Desktop

Configure o Claude Desktop editando o arquivo de configuração:

No MacOS: ~/Library/Application\ Support/Claude/claude_desktop_config.json
No Windows: %APPDATA%/Claude/claude_desktop_config.json
No Linux: ~/.config/Claude/claude_desktop_config.json

Adicione o seguinte ao seu arquivo de configuração:

"mcpServers": {
  "lineai-mcp-server": {
    "command": "uvx",
    "args": [
      "lineai-mcp-server@latest"
    ],
    "env": {
      "LINEAI_SERVER_HOST": "<url to the server e.g. https://myco.app.lineai.net>",
      "LINEAI_USERNAME": "<my username>",
      "LINEAI_PASSWORD": "<my password>",
      "LINEAI_WORKSPACE_NAME": "<my workspace>"
    }
  }
}

Nota: Em alguns sistemas, você pode precisar usar o caminho completo para o executável uvx em vez de apenas "uvx". Por exemplo: /home/user/.local/bin/uvx no Linux/Mac ou C:\Users\username\AppData\Local\astral\uvx.exe no Windows.

Após adicionar a configuração, reinicie o Claude Desktop para aplicar as alterações.

Configuração do Windsurf IDE

Para executar este servidor MCP com Windsurf IDE:

Configure o Windsurf IDE:

Para configurar o Windsurf IDE, você precisa criar ou modificar o arquivo de configuração ~/.codeium/windsurf/mcp_config.json.

Adicione a seguinte configuração ao seu arquivo:

"mcpServers": {
  "lineai-mcp-server": {
    "command": "uvx",
    "args": [
      "lineai-mcp-server@latest"
    ],
    "env": {
      "LINEAI_SERVER_HOST": "<url to the server e.g. https://myco.app.lineai.net>",
      "LINEAI_USERNAME": "<my username>",
      "LINEAI_PASSWORD": "<my password>",
      "LINEAI_WORKSPACE_NAME": "<my workspace>"
    }
  }
}

Nota: Em alguns sistemas, você pode precisar usar o caminho completo para o executável uvx em vez de apenas "uvx". Por exemplo: /home/user/.local/bin/uvx no Linux/Mac ou C:\Users\username\AppData\Local\astral\uvx.exe no Windows.

Após adicionar a configuração, reinicie o Windsurf IDE ou atualize as ferramentas para aplicar as alterações.

Configuração do Cursor

Para configurar o servidor MCP da Lineai no Cursor:

Configure o servidor MCP criando um arquivo .cursor/mcp.json:

{
  "mcpServers": {
    "lineai-mcp-server": {
      "command": "uvx",
      "args": [
        "lineai-mcp-server@latest"
      ],
      "env": {
        "LINEAI_SERVER_HOST": "<url to the server e.g. https://myco.app.lineai.net>",
        "LINEAI_USERNAME": "<my username>",
        "LINEAI_PASSWORD": "<my password>",
        "LINEAI_WORKSPACE_NAME": "<my workspace>",
        "LINEAI_DEBUG_MODE": "true"
      }
    }
  }
}

Nota: Em alguns sistemas, você pode precisar usar o caminho completo para o executável uvx em vez de apenas "uvx". Por exemplo: /home/user/.local/bin/uvx no Linux/Mac ou C:\Users\username\AppData\Local\astral\uvx.exe no Windows.

Reinicie o Cursor para aplicar as alterações.

As ferramentas do servidor MCP da Lineai agora estarão disponíveis no seu workspace do Cursor.

Instruções/Regras para o Assistente de IA

Para ajudar o assistente de IA a usar as ferramentas da Lineai de forma eficaz, você pode adicionar as seguintes instruções/regras à configuração do seu cliente. Recomendamos personalizar essas instruções para alinhar com os padrões de codificação, melhores práticas e requisitos de fluxo de trabalho específicos da sua equipe:

Quando a API de grafo estiver disponível no seu host Lineai, estenda suas regras com a mesma orientação que o servidor já anuncia em seu MCP instructions: use ferramentas lineai-graph-* (search, impact, path-explain, validate-change-scope, owners, capabilities) para descoberta limitada de grafos; se as chamadas de grafo falharem com "não disponível", recorra a lineai-method-impact / lineai-database-impact.

Instruções para VS Code (GitHub Copilot)

Crie um arquivo .vscode/copilot-instructions.md com o seguinte conteúdo:

# Lineai MCP Server Instructions

When modifying existing code methods:
- Use lineai-method-impact to analyze code changes
- Use lineai-database-impact for database modifications
- When the Lineai graph API is available, use lineai-graph-* tools (search, impact, path-explain, validate-change-scope, owners, capabilities) for bounded graph discovery; otherwise rely on method/database impact tools
- Highlight impact results for the modified methods

When modifying SQL code or database entities:
- Always use lineai-database-impact to analyze potential impacts
- Highlight impact results for the modified database entities

To use the Lineai tools effectively:
- For code impacts: Ask about specific methods or functions
- For database relationships: Ask about tables, views, or columns
- For graph discovery: Prefer lineai-graph-* tools when available
- Review the impact results before making changes
- Consider both direct and indirect impacts

Instruções para Claude Desktop

Crie um arquivo ~/.claude/instructions.md com o seguinte conteúdo:

# Lineai MCP Server Instructions

When modifying existing code methods:
- Use lineai-method-impact to analyze code changes
- Use lineai-database-impact for database modifications
- When the Lineai graph API is available, use lineai-graph-* tools (search, impact, path-explain, validate-change-scope, owners, capabilities) for bounded graph discovery; otherwise rely on method/database impact tools
- Highlight impact results for the modified methods

When modifying SQL code or database entities:
- Always use lineai-database-impact to analyze potential impacts
- Highlight impact results for the modified database entities

To use the Lineai tools effectively:
- For code impacts: Ask about specific methods or functions
- For database relationships: Ask about tables, views, or columns
- For graph discovery: Prefer lineai-graph-* tools when available
- Review the impact results before making changes
- Consider both direct and indirect impacts

Regras para Windsurf IDE

Crie ou modifique o arquivo markdown ~/.codeium/windsurf/memories/global_rules.md com o seguinte conteúdo:

When modifying existing code methods:
- Use lineai-method-impact to analyze code changes
- Use lineai-database-impact for database modifications
- When the Lineai graph API is available, use lineai-graph-* tools (search, impact, path-explain, validate-change-scope, owners, capabilities) for bounded graph discovery; otherwise rely on method/database impact tools
- Highlight impact results for the modified methods

When modifying SQL code or database entities:
- Always use lineai-database-impact to analyze potential impacts
- Highlight impact results for the modified database entities

To use the Lineai tools effectively:
- For code impacts: Ask about specific methods or functions
- For database relationships: Ask about tables, views, or columns
- For graph discovery: Prefer lineai-graph-* tools when available
- Review the impact results before making changes
- Consider both direct and indirect impacts

Regra Global do Cursor

Para configurar regras da Lineai no Cursor:

Abra as Configurações do Cursor
Navegue até a seção "Regras"
Adicione o seguinte conteúdo às "Regras do Usuário":

# Lineai MCP Server Rules
## Codebase
- The Lineai MCP Server is for java, javascript, typescript, and C# dotnet codebases
- don't run the tools on python or other non supported codebases
## AI Assistant Behavior
- When modifying existing code methods:
  - Use lineai-method-impact to analyze code changes
  - Use lineai-database-impact for database modifications
  - When the Lineai graph API is available, use lineai-graph-* tools (search, impact, path-explain, validate-change-scope, owners, capabilities) for bounded graph discovery; otherwise rely on method/database impact tools
  - Highlight impact results for the modified methods
- When modifying SQL code or database entities:
  - Always use lineai-database-impact to analyze potential impacts
  - Highlight impact results for the modified database entities
- To use the Lineai tools effectively:
  - For code impacts: Ask about specific methods or functions
  - For database relationships: Ask about tables, views, or columns
  - Review the impact results before making changes
  - Consider both direct and indirect impacts

Variáveis de Ambiente

As seguintes variáveis de ambiente podem ser configuradas para personalizar o comportamento do servidor:

LINEAI_SERVER_HOST: A URL do servidor Lineai.
LINEAI_USERNAME: Seu nome de usuário da Lineai.
LINEAI_PASSWORD: Sua senha da Lineai.
LINEAI_WORKSPACE_NAME: O nome do workspace a ser usado.
LINEAI_DEBUG_MODE: Defina como true para habilitar o modo de depuração. Quando habilitado, arquivos de depuração adicionais, como timing_log.txt e impact_data*.json, serão gerados. O padrão é false.

Somente testes

LINEAI_GRAPH_E2E_REQUIRED: Defina como 1 ao executar testes de integração MCP de grafo se você quiser que APIs de grafo ausentes (HTTP 404 / "Graph API not available") falhem a suíte em vez de pular esses testes.

Exemplo de Configuração

"env": {
  "LINEAI_SERVER_HOST": "<url to the server e.g. https://myco.app.lineai.net>",
  "LINEAI_USERNAME": "<my username>",
  "LINEAI_PASSWORD": "<my password>",
  "LINEAI_WORKSPACE_NAME": "<my workspace>",
  "LINEAI_DEBUG_MODE": "true"
}

Fixando a versão

em vez de usar a versão mais recente do servidor, você pode fixar uma versão específica alterando o campo args para corresponder à versão no pypi, por exemplo.

    "args": [
      "lineai-mcp-server@0.2.2"
    ],

Compatibilidade de Versões

Este servidor MCP tem os seguintes requisitos de compatibilidade de versão:

Versão 0.3.1 e anteriores: Compatível com todas as versões da API Lineai
Versão 0.4.0 e superiores: Requer versão 25.10.0 ou superior da API Lineai

Se você estiver atualizando, certifique-se de que seu servidor Lineai atenda ao requisito mínimo de versão da API.

Ferramentas de grafo: Exigem que sua implantação Lineai sirva os endpoints de grafo sob /api/ai-retrieval/graph/. Implantações mais antigas ou parciais podem retornar 404; as ferramentas MCP exibem isso como um erro claro em vez de falhas opacas.

Registro de Depuração

Quando LINEAI_DEBUG_MODE=true, arquivos de depuração são gravados no diretório temporário do sistema:

Windows: %TEMP%\lineai-mcp-server (tipicamente C:\Users\{username}\AppData\Local\Temp\lineai-mcp-server)
macOS: /tmp/lineai-mcp-server (ou $TMPDIR/lineai-mcp-server se definido)
Linux: /tmp/lineai-mcp-server (ou $TMPDIR/lineai-mcp-server se definido)

Os arquivos de depuração incluem:

timing_log.txt - Informações de tempo de desempenho
impact_data_*.json - Dados brutos de análise de impacto para solução de problemas

Encontrando seu diretório de logs:

import tempfile
import os
print("Log directory:", os.path.join(tempfile.gettempdir(), "lineai-mcp-server"))

Testes

Executando Testes Unitários

O projeto usa unittest para testes. Você pode executar testes unitários sem dependências externas:

python -m unittest discover -s test -p "unit_*.py"

Os testes unitários usam dados simulados e não exigem conexão com um servidor Lineai.

Testes de Integração (Opcional)

Se você quiser executar testes de integração que se conectam a um servidor Lineai real:

Copie test/.env.test.example para test/.env.test e preencha com os detalhes do seu servidor Lineai
Execute os testes de integração:

python -m unittest discover -s test -p "integration_*.py"

Nota: Os testes de integração exigem acesso a uma instância do servidor Lineai.

Testes ponta a ponta do MCP de Grafo

test/integration_test_graph.py aciona o caminho real do manipulador MCP (handle_call_tool) para lineai-graph-capabilities e um fluxo encadeado (search → impact → path → validate → owners) contra LINEAI_SERVER_HOST. Configure as credenciais da mesma forma que outros testes de integração (test/.env.test de test/.env.test.example).

Se o host não expor rotas de grafo, os testes pulam por padrão.
Defina LINEAI_GRAPH_E2E_REQUIRED=1 para transformar APIs de grafo ausentes em falhas graves (útil em CI quando o grafo deve estar presente).

A partir da raiz do repositório:

./scripts/run_graph_e2e.sh

Equivalente:

uv run python -m unittest test.integration_test_graph -v

Validação para o Registro Oficial MCP

mcp-name: io.github.lineai-intelligence/lineai-mcp-server