@nogataka/serena-ts

v0.0.14

Published

4 months ago

TypeScript版 Serena

0High
0Medium
0Low

Serena TS

Serena TS は、Python 製のエージェント基盤「Serena」(https://github.com/oraios/serena) を TypeScript / Node.js 上で動作するよう全面移植したプロジェクトです。MCP (Model Context Protocol) サーバーとして動作し、SolidLSP ベースの言語サーバー管理や Serena 固有のツール群を TypeScript で再構築しています。移植に際しては Python 版と同じディレクトリ構成・ファイル名（拡張子のみ .ts / .tsx）を維持しつつ、@modelcontextprotocol/sdk、zod など Node エコシステムに合わせた依存関係やエラーハンドリングを採用しています。

主な構成

| ディレクトリ / ファイル | 概要 | | --- | --- | | src/serena | エージェント本体、CLI、各種ツール・コンフィグ周りのロジック | | src/solidlsp | SolidLSP 連携と言語サーバーごとのランタイム管理実装 | | src/serena/resources | Serena が自動生成・参照する YAML テンプレート群 | | test/ | Vitest によるユニットテスト・スモークテスト | | docs/ | 移植計画、タスク管理、言語サーバー対応状況などの補足資料 | | tsconfig*.json | ビルド・テスト・Lint 用 TypeScript 設定 |

環境要件

Node.js >= 20.11.0
pnpm (推奨: v8 以降)
macOS / Linux / Windows に対応（Windows では ensureDefaultSubprocessOptions により windowsHide などを自動付与）
言語サーバーの一部は追加のランタイム（nix, rustup, gem, dotnet, go など）や外部コマンドを必要とします

セットアップ手順

pnpm install
# 必要に応じてビルド
pnpm build

pnpm build を実行すると TypeScript のトランスパイルに加えて src/serena/resources/ 以下の YAML テンプレート類も dist/serena/resources/ にコピーされ、npx 経由で配布した際にもコンテキスト定義が参照できるようになります。

テストや開発時に外部バイナリのダウンロードを抑止したい場合は、SERENA_SKIP_RUNTIME_INSTALL=1 を設定してください。

開発用コマンド

| コマンド | 説明 | | --- | --- | | pnpm lint | ESLint による静的解析 | | pnpm test | Vitest 実行（ユニット / スモーク） | | pnpm typecheck | tsc --noEmit での型検証 | | pnpm build | 生成物を dist/ に出力 | | pnpm format / pnpm format:check | Prettier による整形 |

ユーザーガイド

CLI はまだパッケージ化していないため、開発ツリー上では pnpm exec tsx src/serena/cli.ts <command> の形式で呼び出します。長期的には dist/ から node dist/index.js での起動も想定しています。

1. 初期設定フロー

Serena 管理ディレクトリの生成
```
pnpm exec tsx src/serena/cli.ts config edit
```
初回実行時は ~/.serena-ts/serena_config.yml をテンプレートから生成し、既定エディタで開きます。
プロジェクト設定 (project.yml) の生成
```
pnpm exec tsx src/serena/cli.ts project generate-yml /path/to/project
```
言語を手動指定したい場合は --language <lang> を付与します。生成された YAML をプロジェクトルートに配置してください。
モード / コンテキストの確認とカスタマイズ
- 一覧表示: mode list / context list
- テンプレートコピー: mode create --from-internal default-editor など
- 編集: mode edit <name> / context edit <name>
- カスタム削除: mode delete <name> / context delete <name> いずれも pnpm exec tsx src/serena/cli.ts にサブコマンドを続けて実行します。
プロンプトテンプレートの更新 独自プロンプトを用意する場合は、src/serena/resources/prompt_templates/ 以下のテンプレートを ~/.serena-ts/prompt_templates/ にコピーして編集し、prompts グループコマンドで管理します。

2. MCP サーバーの起動

SERENA_SKIP_RUNTIME_INSTALL=1 pnpm exec tsx src/serena/cli.ts start-mcp-server \
  --project /path/to/project \
  --context ide-assistant \
  --mode default-editor \
  --transport stdio

主なオプション:

--transport: stdio (既定) / sse / streamable-http から選択
--enable-web-dashboard, --enable-gui-log-window: Config の設定を一時的に上書き
--log-level, --trace-lsp-communication: ログ詳細度や LSP トレースの制御
--tool-timeout: ツール実行のタイムアウト秒数
--instructions-override: MCP クライアントに渡す初期インストラクションをカスタム指定

サーバー起動後は、必要に応じてダッシュボード (--enable-web-dashboard) や GUI ログビューア (--enable-gui-log-window) を利用できます。GUI ログは GuiLogViewer 経由でブラウザが自動起動し、logs/ ディレクトリにも出力されます。

MCP クライアント（Codex など）からの接続例

npx で公開パッケージを取得する場合、mcp_servers.toml の設定キーを serena-ts に合わせてください。

[mcp_servers.serena-ts]
command = "npx"
args = ["-y", "@nogataka/serena-ts@latest", "serena-ts", "start-mcp-server", "--context", "codex", "--transport", "stdio"]

CLI 側の --context や --mode は必要に応じて追加してください。serena-ts コマンドは package.json の bin.serena-ts で ./dist/cli.js にマッピングされています。

3. プロジェクト / ツール管理

project generate-yml: プロジェクト設定 YAML の生成（上記手順参照）
tools list: 有効化されているツールを確認
tools describe <toolName>: ツールごとの説明・必須マーカーを参照
project グループのその他サブコマンド (index, health-check など) は現時点では未実装であり、実装予定時期を CLI がメッセージとして返します。

4. 主要な環境変数

| 変数 | 用途 | | --- | --- | | SERENA_SKIP_RUNTIME_INSTALL | 1 の場合、言語サーバーなど外部バイナリの自動インストールをスキップ | | SERENA_ASSUME_<LANG> | 各言語サーバーで既存ランタイムを仮定（例: SERENA_ASSUME_GOPLS, SERENA_ASSUME_NIXD, SERENA_ASSUME_SOURCEKIT）| | SERENA_<LANG>_PATH | バイナリパスの明示指定（例: SERENA_RUBY_BINARY, SERENA_ZLS_PATH）| | EDITOR | mode edit 等で使用する既定エディタ | | SERENA_SKIP_EDITOR | 1 の場合、CLI が自動でエディタを開かない |

環境変数の完全な一覧や詳細は src/solidlsp/language_servers/*.ts および src/serena/config/*.ts を参照してください。

5. 言語サーバー対応状況 (2025-10-27 時点)

対応済み: Bash, C#, C/C++, Clojure, Dart, Go, Java, Kotlin, Lua, Nix, PHP, Python (Jedi / Pyright), R, Ruby (Ruby LSP / Solargraph), Rust, Swift, Terraform, TypeScript / JavaScript, Vue (VTS), Zig など
除外: AL Language Server, elixir_tools, OmniSharp（TypeScript 版では対象外）
未対応: なし（Python 版と同じ範囲をカバー）

最新の対応表やサブタスク進捗は docs/ts_port_task_tracker.md を参照してください。

Claude Code への接続手順

Claude Code ではプロジェクトごとに MCP サーバーを追加します。TypeScript 版 Serena を使う場合でも手順はほぼ同じです。

プロジェクトのルートディレクトリで次のコマンドを実行します。
```
claude mcp add serena-ts -- npx -y @nogataka/serena-ts@latest serena-ts start-mcp-server --context ide-assistant --project "$(pwd)" --transport stdio
```
- serena-ts が Claude Code 上でのサーバー識別子になります（任意で変更可）。
- --context ide-assistant は Claude Code 向けに最適化した設定です。用途に応じて desktop-app など他のコンテキストへ切り替えても構いません。
- --project にはコードベースのルートパスを指定してください。$(pwd) を使うとカレントディレクトリをそのまま渡せます。
- --transport stdio は標準入出力経由での通信を指定します。Claude Code は stdio を用いるため、この指定が必要です。
追加が完了したら、claude mcp list で登録済みサーバーを確認できます。必要に応じて claude mcp remove serena-ts で削除し、再登録してください。
会話を開始すると Claude が Serena TS の初期インストラクション（initial_instructions）を自動で読み込みます。もし読み込みに失敗した場合は、Claude に「Serena の初期インストラクションを読んで」と依頼するか、/mcp__serena-ts__initial_instructions を実行してください（初期インストラクションツールを有効化している場合）。
コンテキストやモードをカスタマイズしたい場合は、~/.serena-ts/context/ 配下に YAML を配置した上で --context / --mode オプションで指定できます。

Codex (OpenAI CLI) への接続手順

Codex CLI はグローバル設定で MCP サーバーを追加します。~/.codex/config.toml に以下のエントリを追加してください。

[mcp_servers.serena-ts]
command = "npx"
args = ["-y", "@nogataka/serena-ts@latest", "serena-ts", "start-mcp-server", "--context", "codex", "--transport", "stdio"]

--context codex は Codex 特有の I/O や制約に対応するための設定です。Codex では codex コンテキストを使うことでツールの動作が最適化されます。
Codex 起動後、チャット内で「Serena で現在のディレクトリをプロジェクトとしてアクティブ化して」と依頼してください。プロジェクトをアクティブ化しないとツールを利用できません。
ダッシュボード (--enable-web-dashboard) を利用する場合、Codex のサンドボックスではブラウザが自動起動しないことがあります。その場合は http://localhost:24282/dashboard/index.html （ポートは環境により変わります）へブラウザでアクセスしてください。
Codex の UI ではツール実行が failed と表示されることがありますが、実際には処理が成功しているケースが多いです。ログ (~/.codex/log/codex-tui.log) を併せて確認してください。

これらの設定を行うことで、Claude Code / Codex ともに npx -y @nogataka/serena-ts@latest を通して TypeScript 版 Serena MCP サーバーを利用できます。npm publish 後に @nogataka/serena-ts のバージョンを最新に保つようご注意ください。

Claude Desktop への接続手順

Claude Desktop (Windows/macOS) では claude_desktop_config.json に MCP サーバー設定を追加します。メニューの File → Settings → Developer → MCP Servers → Edit Config を開き、以下のいずれかの設定を追記してください。識別子は例として serena-ts を使用しています。

npm (npx) 経由で最新版を利用する場合

{
  "mcpServers": {
    "serena-ts": {
      "command": "npx",
      "args": ["-y", "@nogataka/serena-ts@latest", "serena-ts", "start-mcp-server", "--context", "desktop-app", "--transport", "stdio"]
    }
  }
}

ローカルのクローンから開発ビルドを直接利用する場合
```
{
  "mcpServers": {
    "serena-ts": {
      "command": "node",
      "args": ["/absolute/path/to/serena-ts/dist/cli.js", "start-mcp-server", "--context", "desktop-app", "--transport", "stdio", "--project", "/absolute/path/to/project"]
    }
  }
}
```
- dist/cli.js を呼び出す前に pnpm build を実行し、dist/ に成果物を生成しておいてください。
- --project は必要に応じて省略できます（省略時は起動後にチャットからプロジェクトをアクティブ化します）。

Docker イメージを使う場合（PoC）

{
  "mcpServers": {
    "serena-ts": {
      "command": "docker",
      "args": [
        "run", "--rm", "-i",
        "-v", "/path/to/your/projects:/workspace/projects",
        "ghcr.io/nogataka/serena-ts:latest",
        "serena-ts", "start-mcp-server", "--context", "desktop-app", "--transport", "stdio"
      ]
    }
  }
}

公式イメージを公開する場合はリポジトリ URL やボリューム設定を用途に合わせて変更してください。

注意事項

Windows でパスを指定する場合はバックスラッシュを二重にする (\\) か、スラッシュ (/) を利用してください。
設定を保存したら Claude Desktop を完全終了（システムトレイのアイコンも終了）し、再起動すると Serena TS のツールが利用可能になります。
desktop-app コンテキストは Claude Desktop 向けにチューニングされています。必要に応じて ~/.serena-ts/contexts/ 配下に自作コンテキストを配置し、--context で差し替え可能です。
ダッシュボードを利用したい場合は Config 側で web_dashboard: true を有効にしてください。ブラウザが自動起動しない場合は http://localhost:24282/dashboard/index.html へアクセスできます。
MCP サーバーを終了するにはチャットを閉じるだけでなく、別コンソールから serena-ts プロセスを停止するか、CLI のログを確認しながら Ctrl+C で停止してください。

Claude Desktop の MCP 設定については公式クイックスタートも参考になります。

トラブルシューティング

言語サーバーのダウンロードが失敗する場合: ネットワーク設定を確認し、必要に応じて SERENA_ASSUME_<LANG> でローカルバイナリを指示します。
macOS で pnpm test 実行時に EPERM: operation not permitted, listen が発生する場合: sudo での実行か、環境ポート (SERENA_DASHBOARD_PORT など) の明示指定をご検討ください。
Windows でコンソールウィンドウが一瞬開く場合: 既に ensureDefaultSubprocessOptions が windowsHide を設定しますが、SERENA_VERBOSE_PROCESS=1 を付与すると詳細ログで状況確認ができます。

参考ドキュメント

docs/ts_port_implementation_plan.md: TypeScript 移植全体の方針と決定事項
docs/ts_port_task_tracker.md: サブタスク進捗・言語サーバー対応表
docs/lsp_server_execution_methods.md ほか: SolidLSP 周辺仕様の補足資料

ドキュメントとコードは常に同期させる方針です。新しい機能やタスクを追加した際は、README と docs/ の両方を更新してください。

ライセンス

本リポジトリ（Serena TS）は MIT ライセンスで提供されます。詳細は LICENSE を参照してください。
Serena の Python 版 (https://github.com/oraios/serena) も MIT ライセンスで公開されています。本 TypeScript ポートは Python 版の実装・ドキュメントをベースに再構築しており、オリジナルの著作権表示（Oraios AI）を含めた形で継承しています。
Serena TS への追加実装分は「Serena TS contributors」として明記しています。コントリビューションの際は、MIT ライセンスの条件に同意の上で PR を提出してください。