Typescript MCP

🚀 TypeScript-MCP

AIコーディングエージェント向けのTypeScript型チェックとコードナビゲーションを提供します。tsgoによって動作します。

🚀 クイックスタート

typescript-mcpは、Model Context Protocolのツール呼び出しをtsgoの組み込みLSPサーバーに橋渡しするGoのMCPサーバーです。これにより、コーディングエージェントは正規表現やヒューリスティックに依存することなく、実際のTypeScript型チェックとコードナビゲーションを行うことができます。

サーバーは子プロセスとしてtsgo --lsp --stdioを起動し、JSON-RPCを介して通信し、LSPの応答を簡潔でエージェントに適したJSONに変換します。

✨ 主な機能

• AIコーディングエージェントにTypeScript型チェックとコードナビゲーション機能を提供
• MCPとLSPを橋渡しし、正規表現やヒューリスティックに依存せずに正確な型チェックを可能にする

📦 インストール

前提条件

• Go 1.24+
• tsgo -- グローバルにインストールするか、npxを使用します:

  npm install -g @typescript/native-preview
  # またはインストールせずに実行:
  npx @typescript/native-preview --version
  

インストール手順

最新バージョンをインストールするには:

go install github.com/paulvanbrenk/typescript-mcp/cmd/typescript-mcp@latest

またはソースからビルドするには:

git clone https://github.com/paulvanbrenk/typescript-mcp.git
cd typescript-mcp
go build -o typescript-mcp ./cmd/typescript-mcp

Claude Codeの設定

MCP設定（.mcp.jsonまたはClaude Codeの設定）に以下を追加します:

{
  "mcpServers": {
    "typescript": {
      "command": "typescript-mcp",
      "args": []
    }
  }
}

typescript-mcpがPATHに含まれていない場合は、バイナリの完全パスを使用してください。

💻 使用例

ツールリファレンス

行番号と列番号は1から始まります。

ts_diagnostics

ファイルのTypeScriptエラーと警告を取得します。

リクエスト例:

{
  "file": "/home/user/project/src/index.ts",
  "maxResults": 10
}

レスポンス例:

{
  "diagnostics": [
    {
      "file": "/home/user/project/src/index.ts",
      "line": 12,
      "column": 5,
      "severity": "error",
      "code": 2322,
      "message": "Type 'string' is not assignable to type 'number'."
    }
  ],
  "totalCount": 1,
  "truncated": false
}

ts_definition

シンボルの定義に移動します。シンボルが定義されているファイルと位置を返し、ソース行のプレビューを含みます。

リクエスト例:

{
  "file": "/home/user/project/src/index.ts",
  "line": 10,
  "column": 15
}

レスポンス例:

[
  {
    "file": "/home/user/project/src/utils.ts",
    "line": 3,
    "column": 17,
    "preview": "export function formatDate(date: Date): string {"
  }
]

ts_hover

ある位置のシンボルの型情報とドキュメントを取得します。解決された型シグネチャを返します。

リクエスト例:

{
  "file": "/home/user/project/src/index.ts",
  "line": 5,
  "column": 10
}

レスポンス例 (プレーンテキスト):

(property) AppConfig.port: number

レスポンスは、ホバーコンテンツから抽出された型シグネチャです。Markdownのコードフェンスは削除され、型情報のみが返されます。

ts_references

プロジェクト全体でシンボルのすべての参照を検索します。シンボルが使用されているすべての場所を返し、宣言を含みます。

リクエスト例:

{
  "file": "/home/user/project/src/utils.ts",
  "line": 3,
  "column": 17
}

レスポンス例:

{
  "references": [
    {
      "file": "/home/user/project/src/utils.ts",
      "line": 3,
      "column": 17,
      "preview": "export function formatDate(date: Date): string {"
    },
    {
      "file": "/home/user/project/src/index.ts",
      "line": 10,
      "column": 15,
      "preview": "const result = formatDate(new Date());"
    }
  ],
  "totalCount": 2,
  "truncated": false
}

ts_document_symbols

ファイルのシンボルアウトラインを取得します。すべての関数、クラス、インターフェース、変数とそれらの型のツリーを返します。

リクエスト例:

{
  "file": "/home/user/project/src/utils.ts"
}

レスポンス例:

[
  {
    "name": "formatDate",
    "kind": "function",
    "line": 3,
    "detail": "(date: Date) => string"
  },
  {
    "name": "AppConfig",
    "kind": "interface",
    "line": 8,
    "children": [
      {
        "name": "port",
        "kind": "property",
        "line": 9,
        "detail": "number"
      },
      {
        "name": "host",
        "kind": "property",
        "line": 10,
        "detail": "string"
      }
    ]
  }
]

ts_rename

プロジェクト全体でシンボルをリネームします。このツールはディスクに書き込みます — シンボルを含むすべてのファイルが原子的に更新されます（失敗時にはロールバックされます）。編集が適用された後、LSPが再同期されます。

リクエスト例:

{
  "file": "/home/user/project/src/store.ts",
  "line": 42,
  "column": 14,
  "newName": "repository"
}

レスポンス例:

{
  "newName": "repository",
  "totalEdits": 9,
  "changes": [
    {
      "file": "/home/user/project/src/actions.ts",
      "edits": 8,
      "preview": "import { repository } from '@/lib/store';"
    },
    {
      "file": "/home/user/project/src/store.ts",
      "edits": 1,
      "preview": "export const repository = new Store();"
    }
  ]
}

ts_project_info

TypeScriptプロジェクトの構成情報を取得します。tsconfigのパスとプロジェクトのルートディレクトリを返します。

リクエスト例:

{
  "cwd": "/home/user/project"
}

レスポンス例:

{
  "tsconfigPath": "/home/user/project/tsconfig.json",
  "projectRoot": "/home/user/project"
}

ワークフロー例

編集 - チェック - 修正サイクル

TypeScriptファイルを編集した後、ts_diagnosticsを使用して型エラーをチェックし、修正し、再度確認します:

1. ファイルを編集します（例: 関数シグネチャを変更する）
2. ファイルパスを指定してts_diagnosticsを呼び出し、エラーを取得します
3. 報告されたエラーを修正します
4. 再度ts_diagnosticsを呼び出して、エラーがゼロであることを確認します

コード探索

シンボル、ホバー、定義への移動を使用して、不慣れなコードをナビゲートします:

1. ts_document_symbolsを呼び出して、ファイルの構造の概要を取得します
2. 興味深いシンボルに対してts_hoverを呼び出し、その型シグネチャを表示します
3. ts_definitionを呼び出して、シンボルのソース定義にジャンプします

安全なリファクタリング

1ステップでプロジェクト全体でシンボルをリネームします:

1. シンボルの位置と新しい名前を指定してts_renameを呼び出します
2. 影響を受けるファイルに対してts_diagnosticsを呼び出し、正しさを検証します

または手動でリファクタリングする場合は、まずすべての使用箇所を見つけます:

1. 変更するシンボルに対してts_referencesを呼び出します
2. 返されたすべての場所を編集します
3. 影響を受けるファイルに対してts_diagnosticsを呼び出し、正しさを検証します

🔧 技術詳細

環境変数

開発

ビルド

go build ./cmd/typescript-mcp

テスト

go test ./...

ローカルで実行

# tsgoが利用可能か確認
tsgo --version

# MCPサーバーを実行 (stdioを介して通信)
./typescript-mcp

プロジェクト構造

cmd/typescript-mcp/     エントリポイントとMCPサーバーのセットアップ
internal/
  lsp/                  LSPクライアントとtsgoプロセス管理
    client.go           JSON-RPC接続、LSPメソッドラッパー
    process.go          tsgoプロセスのライフサイクル (起動、停止、解決)
  docsync/              LSPサーバーとのドキュメント同期
    sync.go             オープン/変更/クローズ通知
    uri.go              ファイルパス <-> URI変換
  tools/                MCPツールハンドラー
    tools.go            ツール登録 (スキーマと説明)
    diagnostics.go      ts_diagnosticsハンドラー
    definition.go       ts_definitionハンドラー
    hover.go            ts_hoverハンドラー
    references.go       ts_referencesハンドラー
    rename.go           ts_renameハンドラー (書き込みツール)
    symbols.go          ts_document_symbolsハンドラー
    project.go          ts_project_infoハンドラー
    util.go             共通ユーティリティ (readLine)
cmd/test-client/        実際のプロジェクトに対する手動テスト用のCLI

📄 ライセンス

詳細については LICENSE を参照してください。