MCPサーバーをTypeScriptで自作

実体験に基づいて書かれている。筆者は社内API連携用のMCPサーバーをすでに自作してClaude Codeに繋いだことがあり、最初につまずいたのは実装の難しさではなく、console.logを1行書いたことで起きた静かな失敗だったと述べている。この失敗の仕方はstdioサーバーの仕組みに由来する。プロセスのstdoutはJSON-RPCの通信路そのものなので、そこに別のものを書けば会話が壊れる。ログの逃げ道として推奨されるのが、stderrに出力されるconsole.errorだ。

最初に作るツールとして推奨されているのは、あえて小さなlist_todosだ。ディレクトリを走査して.ts、.tsx、.js、.pyファイル内のTODOとFIXMEコメントを探し、ファイルパスと行番号付きで返す。筆者は、こうしたささやかなツールにも意味があると論じる。チームがすでに気にかけている情報を、LLMが届く範囲に加えられるからだ。

stdoutの罠以外にも、実用的なつまずきがいくつか挙げられている。緩いinputSchema（Zodライブラリで書くツールの引数定義）はクライアントの引数生成を不安定にするため、スキーマは厳密にすべきだ。claude mcp addに渡すエントリポイントは絶対パスが最も安全で、サーバーがClaude Codeを起動したディレクトリに依存しなくなる。また、サーバーを止めずにClaude Codeを終了すると子プロセスが残ることがあるため、開発中はps aux | grep tsxで確認するよう勧めている。最後の助言は、最小構成のツール1つのサーバーから始め、claude mcp addで繋いでから拡張せよというものだ。