codelogic-mcp-server

lineai-mcp-server

AI プログラミングアシスタントで Lineai の豊富なソフトウェア依存関係データを活用するための MCP サーバー です。

ドキュメント

コードから生成されたアーキテクチャドキュメントは docs/ にあります（LIN-737 で追加。LIN-699 の変更に合わせて更新 — PR #61 / neo4cape #1860）。

• docs/architecture.md — アーキテクチャの詳細な分析：モジュールマップ、ツールの概要と各ツールが呼び出す Lineai の /api/... エンドポイント、認証フロー、キャッシュ、エラー処理の分類、設定、パッケージング／リリース、および調査結果。
• docs/architecture-diagrams.md — Mermaid の図のセット（エコシステム、モジュールマップ、呼び出しシーケンス、認証／キャッシュ、エラー分類）。
• docs/rendered-diagrams/ — すべての図を SVG 形式でレンダリングしてコミットしたもの。

コンポーネント

ツール

このサーバーは 8 つのツールを実装しています。2 つの影響分析ツールと、Lineai グラフ HTTP API を利用する 6 つの グラフツールです。

コード分析ツール

• lineai-method-impact：コードへの影響評価を Lineai サーバーの API から取得します。
  • 作業中の「メソッド」を指定します。単純名が複数のリポジトリに存在する可能性がある場合は、「class」に 完全修飾クラス名（例：com.acme.shell.AnalyzeCommands）を渡してください。完全修飾クラス名を指定するとそのクラスが特定されますが、複数のクラスに一致する単純名を指定すると、別のリポジトリのクラスを黙って分析するのではなく、候補を一覧表示する曖昧性ページが返されます。
  • 影響分析は、Lineai グラフ影響エンドポイントからの 範囲を限定した上流方向の探索です（depth 引数。デフォルトは 3、最大は 10）。レポートの Impact scope セクションには、データの取得元（グラフ、またはグラフエンドポイントがデプロイされていない場合は従来の全チェーンエンドポイント）と、結果が完全（ok）か下限値（partial）かが記載されます。部分的な結果が「影響なし」を意味することはありません。
• lineai-database-impact：コードとデータベースエンティティの間の影響を分析します。
  • データベースエンティティの種類（列、テーブル、ビュー）とその名前を指定します。

8 つすべてのツールは、単一の呼び出しの対象を絞るための workspace および materialized_view_id 引数も任意で受け取ります。どちらも指定されておらず、LINEAI_WORKSPACE_NAME も未設定の場合は、サーバーのデフォルトのワークスペースにある最新のマテリアライズドビューが自動的に使用されます。

Graph API ツール

これらは、LINEAI_SERVER_HOST と同じホスト上の /api/ai-retrieval/graph/ 配下にある POST／GET エンドポイントを呼び出します。他の MCP ツールと同じセッション認証を使用します。グラフのルートがデプロイされていない場合、サーバーは「graph not available」のような明確なメッセージを返します（多くの場合、HTTP 404 の後に表示されます）。

• lineai-graph-capabilities：GET — ワークスペースのマテリアライズドビューでサポートされている関係タイプ、制限、フラグを検出します（materializedViewId の解決方法は他のすべてのツールと同じです：明示的な ID → workspace 引数 → LINEAI_WORKSPACE_NAME → サーバーのデフォルト）。
• lineai-graph-search：テキストの query／q および／または identity_prefix でノードを検索します。scan_space（スキャンスペースの ID または表示名）、prefer_latest_scan、limit は任意です。結果はサーバーによってランク付けされます（完全一致する短い名前 → 完全一致する完全修飾名 → クラス形式のラベル → テキストスコア → 最新のスキャン）。data.hits[i] は data.nodes[i] を説明します（score、matchKind、labelTier）。data.totalHitCount は実際の合計件数です。そのため、1 ページ分の結果がすべて表示された場合は「存在しない」ではなく、「クエリを絞り込む」必要があります。
• lineai-graph-impact：seed_node_ids から、範囲を制限して依存関係／影響範囲をたどります。direction は（upstream = シードに依存するもの、downstream、both）、depth は（サーバーのデフォルトは 3、最大 10）を指定します。レスポンスには、status（ok | partial）、truncated、nodeCount、staticAnalysisGap、assumptionsApplied マーカーが含まれます。結果が部分的または機能低下している場合、あるいは古いサーバーがオプションを無視した場合、ツールは JSON の上に注記を表示します。
• lineai-graph-path-explain：from_node_id と to_node_id の間を結ぶ最短経路形式の説明を生成します。
• lineai-graph-validate-change-scope：シードノードと proposed_change_summary を基に、提案された変更のヒューリスティックなチェックリスト／リスク概要を生成します。
• lineai-graph-owners：node_id または identity_prefix でノードを解決し、名前に "owner" を含むプロパティフィールドを提示します。

ツール引数では、MCP スキーマに記載されている場合、snake_case のエイリアス（例：materialized_view_id、seed_node_ids）を使用できます。Lineai に送信されるリクエストボディでは、camelCase の JSON キーを使用します。

インストール

前提条件

MCP サーバーの実行には Astral UV が必要です。インストールしてください。

uvx の MacOS 回避策

MacOS では uvx に既知の問題があり、Cursor などの特定の IDE で Lineai MCP サーバーの起動に失敗し、次のようなエラーが発生することがあります： issue #11 を参照してください。

Failed to connect client closed

これは、Astral uvx が MacOS 上で動作する際の問題と思われます。以下の方法で回避できます：

1. このプロジェクトをローカルにクローンします。
2. mcp.json を設定して、uvx の代わりに uv を使用します。例：

{
  "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"
      }
    }
  }
}

3. Cursor を再起動します。
4. Lineai の Cursor グローバルルールが設定されていることを確認します。
5. Cursor の MCP タブを開き、lineai-mcp-server を更新します。
6. Cursor に既存クラスのコード変更を依頼します。これで MCP サーバーが影響分析を正常に実行できるはずです。

異なる IDE の設定

Visual Studio Code の設定

VS Code でこの MCP サーバーを設定するには、次の手順を実行します。

1. まず、VS Code で GitHub Copilot のエージェントモードが有効になっていることを確認します。

2. ワークスペースに .vscode/mcp.json ファイルを作成し、次の設定を追加します。

{
  "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"
      }
    }
  }
}

注： システムによっては、「uvx」だけでなく、uvx 実行ファイルのフルパスを指定する必要があります。たとえば、Linux/Mac では /home/user/.local/bin/uvx、Windows では C:\Users\username\AppData\Local\astral\uvx.exe を指定します。

3. または、コマンドパレットから MCP: Add Server コマンドを実行し、サーバー情報を入力します。

4. MCP サーバーを管理するには、コマンドパレットから MCP: List Servers コマンドを使用します。

5. 設定が完了すると、サーバーのツールを Copilot のエージェントモードで使用できるようになります。必要に応じて、エージェントモードでチャットビューの「ツール」ボタンをクリックし、特定のツールのオン／オフを切り替えられます。

6. エージェントモードで Lineai のツールを使用するには、コードへの影響やデータベースの関連性について具体的に質問します。エージェントが適切なツールを使用します。

Claude Desktop の設定

設定ファイルを編集して Claude Desktop を設定します。

• MacOS の場合：~/Library/Application\ Support/Claude/claude_desktop_config.json
• Windows の場合：%APPDATA%/Claude/claude_desktop_config.json
• Linux の場合：~/.config/Claude/claude_desktop_config.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>"
    }
  }
}

注： システムによっては、「uvx」だけでなく、uvx 実行ファイルのフルパスを指定する必要があります。たとえば、Linux/Mac では /home/user/.local/bin/uvx、Windows では C:\Users\username\AppData\Local\astral\uvx.exe を指定します。

設定を追加したら、Claude Desktop を再起動して変更を適用します。

Windsurf IDE の設定

Windsurf IDE でこの MCP サーバーを実行するには、次の手順を実行します。

Windsurf IDE の設定：

Windsurf IDE を設定するには、~/.codeium/windsurf/mcp_config.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>"
    }
  }
}

注： システムによっては、「uvx」だけでなく、uvx 実行ファイルのフルパスを指定する必要があります。たとえば、Linux/Mac では /home/user/.local/bin/uvx、Windows では C:\Users\username\AppData\Local\astral\uvx.exe を指定します。

設定を追加したら、Windsurf IDE を再起動するか、ツールを更新して変更を適用します。

Cursor の設定

Cursor で Lineai MCP サーバーを設定するには、次の手順を実行します。

1. .cursor/mcp.json ファイルを作成して MCP サーバーを設定します。

{
  "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"
      }
    }
  }
}

注： システムによっては、「uvx」だけでなく、uvx 実行ファイルのフルパスを指定する必要があります。たとえば、Linux/Mac では /home/user/.local/bin/uvx、Windows では C:\Users\username\AppData\Local\astral\uvx.exe を指定します。

2. Cursor を再起動して変更を適用します。

これで、Lineai MCP サーバーのツールを Cursor ワークスペースで使用できるようになります。

AI アシスタントへの指示／ルール

AI アシスタントが Lineai のツールを効果的に使用できるように、以下の指示／ルールをクライアントの設定に追加できます。チーム固有のコーディング規約、ベストプラクティス、ワークフロー要件に合わせて、これらの指示をカスタマイズすることをおすすめします。

Lineai ホストでグラフ API を利用できる場合は、サーバーが MCP の instructions ですでに提示しているものと同じガイダンスをルールに追加してください。範囲を限定したグラフ探索には lineai-graph-* ツール（search、impact、path-explain、validate-change-scope、owners、capabilities）を使用し、グラフ呼び出しが「not available」で失敗した場合は、lineai-method-impact ／ lineai-database-impact にフォールバックします。

VS Code（GitHub Copilot）の指示

.vscode/copilot-instructions.md ファイルを作成し、以下の内容を追加します。

# 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

Claude Desktop の指示

~/.claude/instructions.md ファイルを作成し、以下の内容を追加します。

# 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

Windsurf IDE のルール

~/.codeium/windsurf/memories/global_rules.md Markdown ファイルを作成または編集し、以下の内容を追加します。

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

Cursor のグローバルルール

Cursor で Lineai のルールを設定するには：

1. Cursor の設定を開きます
2. 「Rules」セクションに移動します
3. 次の内容を「User Rules」に追加します：

# 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

環境変数

次の環境変数を設定して、サーバーの動作をカスタマイズできます：

• LINEAI_SERVER_HOST：Lineai サーバーの URL（必須）。すべての API パス（/api/authenticate、/api/ai-retrieval/...、/api/dependency/...、/api/materialized-view...）がこの URL に追加されます。
• LINEAI_USERNAME：Lineai のユーザー名（必須）。
• LINEAI_PASSWORD：Lineai のパスワード（必須）。
• LINEAI_WORKSPACE_NAME：使用するデフォルトのワークスペース。省略可能です。個々のツール呼び出しで workspace / materialized_view_id 引数を使って上書きできます。また、何も指定されていない場合は、サーバーのデフォルトのワークスペースにある最新のマテリアライズドビューが使用されます。
• LINEAI_DEBUG_MODE：デバッグモードを有効にするには、true に設定します。有効にすると、timing_log.txt や impact_data*.json などの追加のデバッグファイルが生成されます。デフォルトは false です。

チューニング（省略可能 — サーバー起動時に一度だけ読み込み）

• LINEAI_TOKEN_CACHE_TTL：認証トークンのキャッシュ有効期間（秒）。デフォルトは 3600 です。
• LINEAI_METHOD_CACHE_TTL：メソッドのショートネーム検索結果のキャッシュ有効期間（秒）。デフォルトは 300 です。
• LINEAI_IMPACT_CACHE_TTL：影響分析結果のキャッシュ有効期間（秒）。デフォルトは 300 です。
• LINEAI_MV_CACHE_TTL：マテリアライズドビュー解決結果のキャッシュ有効期間（ワークスペース名 / サーバーのデフォルト → ビュー ID、秒）。デフォルトは 300 です。
• LINEAI_REQUEST_TIMEOUT：すべての Lineai API 呼び出しに対する HTTP リクエスト全体のタイムアウト（秒）。デフォルトは 120.0 です。グラフの影響分析呼び出しはサーバー側で制限されています（深度 / ノード数 / 関係数の上限、クエリタイムアウトは 60 秒）。したがって、ここでタイムアウトが発生する場合、通常は深度が大きすぎます。depth を 1～2 にして再試行してください。
• LINEAI_CONNECT_TIMEOUT：HTTP 接続タイムアウト（秒）。デフォルトは 30.0 です。
• LINEAI_METHOD_IMPACT_BACKEND：graph（デフォルト）は、制限付きグラフ影響分析エンドポイントから lineai-method-impact サブグラフを取得します。従来の /api/dependency/impact/full リストへのフォールバックは、グラフのルートが見つからない場合（neo4cape のエンティティメッセージを含まない 404）のみ行われます。ノード名を示す 404（「Unable to locate node …」）は、検索結果とビューの不一致として報告されます。不明な ID に対する従来のトラバーサルは空の結果を返し、それが「孤立している」と誤解されるためです。legacy は従来のエンドポイントを強制的に使用します（制限なしの完全な上流チェーン）。呼び出しごとに読み込まれます。

テストのみ

• LINEAI_TEST_MODE：任意の値を設定すると、サーバーは .env ファイルの読み込みをスキップし、テストで環境を完全に制御できるようになります。
• LINEAI_GRAPH_E2E_REQUIRED：グラフ MCP 統合テストの実行時に、グラフ API が見つからない場合（HTTP 404 / 「Graph API not available」）にテストをスキップせず、テストスイートを失敗させるには、1 に設定します。

設定例

"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"
}

バージョンの固定

サーバーの最新バージョンではなく特定のバージョンを固定するには、pypi のバージョンに合わせて args フィールドを変更します。例：

    "args": [
      "[email protected]"
    ],

バージョン互換性

この MCP サーバーには、次のバージョン互換性要件があります。

• バージョン 0.3.1 以下：すべての Lineai API バージョンと互換性があります
• バージョン 0.4.0 以上：Lineai API バージョン 25.10.0 以降が必要です

アップグレードする場合は、お使いの Lineai サーバーが最小 API バージョン要件を満たしていることを確認してください。

グラフツール：Lineai のデプロイ環境で、/api/ai-retrieval/graph/ 配下のグラフエンドポイントが提供されている必要があります。古いデプロイ環境や一部機能のみのデプロイ環境では 404 が返されることがあります。その場合、MCP ツールは不明瞭なエラーではなく、明確なエラーを表示します。

ランキング検索／影響範囲の制限（LIN-870）：ランキング、hits、実際の totalHitCount、scan_space／prefer_latest_scan、および depth／direction／status: partial の影響範囲の仕様を使用するには、neo4cape LIN-870 を含む Lineai サーバーが必要です。古いサーバーでもツールは動作します。検索結果はサーバーの未ランキング順で返され、影響分析はサブグラフ全体を対象に実行されます。また、無視されたオプションは *_not_implemented／*_reserved_* マーカーとして返され、ツールは「x は無視されました（古いサーバー）」と表示します。グラフエンドポイントがない場合、lineai-method-impact は自動的に従来の影響分析エンドポイントにフォールバックします。

デバッグログ

LINEAI_DEBUG_MODE=true の場合、デバッグファイルはシステムの一時ディレクトリに書き込まれます。

• Windows：%TEMP%\lineai-mcp-server（通常は C:\Users\{username}\AppData\Local\Temp\lineai-mcp-server）
• macOS：/tmp/lineai-mcp-server（または設定されている場合は $TMPDIR/lineai-mcp-server）
• Linux：/tmp/lineai-mcp-server（または設定されている場合は $TMPDIR/lineai-mcp-server）

デバッグファイルの内容：

• timing_log.txt - パフォーマンス計測情報
• impact_data_*.json - トラブルシューティング用の影響分析生データ

ログディレクトリの確認方法：

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

テスト

単体テストの実行

このプロジェクトではテストに unittest を使用しています。外部依存関係なしで単体テストを実行できます。

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

単体テストではモックデータを使用するため、Lineai サーバーへの接続は不要です。test/unit_test_handlers.py には、TestMethodNodeSelection テーブル（LIN-870 の 3 つのリポジトリにおける AnalyzeCommands のケース：完全修飾クラス名 → 正しいリポジトリ、単純名 → 曖昧性ページ、別リポジトリの完全修飾名 → 見つからないページ、未解決の参照は選択されない）が含まれています。また、グラフバックエンド／従来方式へのフォールバック／部分的な結果を扱うハンドラーのケースも含まれています。test/unit_test_graph_tools.py では、部分的な結果に関する注記と古いサーバー向けのマーカーをテストします。

統合テスト（任意）

実際の Lineai サーバーに接続する統合テストを実行する場合：

1. test/.env.test.example を test/.env.test にコピーし、お使いの Lineai サーバーの情報を入力します
2. 統合テストを実行します：

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

注：統合テストには Lineai サーバーインスタンスへのアクセスが必要です。

グラフ MCP のエンドツーエンドテスト

test/integration_test_graph.py は、LINEAI_SERVER_HOST に対して、lineai-graph-capabilities と一連のフロー（検索 → 影響分析 → パス → 検証 → オーナー）について、実際の MCP ハンドラーパス（handle_call_tool）を実行します。認証情報は、他の統合テストと同じ方法で設定してください（test/.env.test.example から test/.env.test を作成）。

• ホストがグラフルートを公開していない場合、テストはデフォルトでスキップされます。
• LINEAI_GRAPH_E2E_REQUIRED=1 を設定すると、グラフ API が見つからない場合にテストが失敗するようになります（CI でグラフ API の存在が必須の場合に便利です）。

リポジトリのルートから：

./scripts/run_graph_e2e.sh

同等のコマンド：

uv run python -m unittest test.integration_test_graph -v

公式 MCP レジストリ向けの検証

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