MCPサーバ(Model Context Protocol server)をTypeScriptでつくってnpmに公開する

2025-01-20

MCPサーバをTypeScriptで作って、npmに公開する手順をまとめました。

作成したサーバーをnpxで呼び出せるようになります。

プロジェクトの作成

create-server を使うと、Resources, Tools, Promptsのサンプルが実装されているテンプレートを簡単に作成できます。

Resources, Tools, PromptsそれぞれでHandlerを定義する形になっています。
各機能の一覧(リスト)の公開とその実装で6種類のスキーマが設定できます。

npx @modelcontextprotocol/create-server sample-project

 npx @modelcontextprotocol/create-server sample-project
? What is the name of your MCP server? sample-project
? What is the description of your server? A Model Context Protocol server
? Would you like to install this server for Claude.app? No
✔ MCP server created successfully!

Next steps:
  cd sample-project
  npm install
  npm run build  # or: npm run watch
  npm link       # optional, to make available globally

環境の構築と起動の確認

以下で環境を構築します。

npm install
npm run build

npm run inspectorでブラウザが立ち上がり動作を確認できます。

npm run inspector
# npx @modelcontextprotocol/inspector path\to\sample-project\build\index.js

Claude DesktopやClineから参照する場合の設定は以下の通りです。

"sample-project": {
    "command": "node",
    "args": [
        "path\\to\\sample-project\\build\\\index.js"
    ]
}

テスト

開発を本格的に進める前に、jestでテストを実施できるようにしておきます。 (VSCodeの拡張機能 Jest も入れておくと便利です)

npm install --save-dev jest @types/jest ts-jest

package.jsonにテスト用のコマンドを追加しておきます。

"scripts": {
  ...
  "test": "jest",
  ...
},

jest.config.jsは以下のようにしました。

/** @type {import('ts-jest').JestConfigWithTsJest} */
export default {
  preset: 'ts-jest',
  testEnvironment: 'node',
  extensionsToTreatAsEsm: ['.ts'],
  moduleNameMapper: {
    '^(\\.{1,2}/.*)\\.js$': '$1',
  },
  transform: {
    '^.+\\.tsx?$': ['ts-jest', {
      useESM: true,
    }],
  },
};

公開用にpackage.jsonは、"private": true,を削除して以下記載しました。(参考package.json)

{
  ...
  "bin": {
    "sample-project": "build/index.js"
  },
  ...
  "repository": {
    "type": "git",
    "url": "git+https://github.com/~~~~~~~~.git"
  },
  "keywords": [
    "mcp",
    "server"
  ],
  "homepage": "https://example.com/",
  "license": "MIT",
  "author": "名前",
  ...
  "types": "build/index.d.ts"
}

ビルド、テスト、動作確認は以下コマンドで行なえます。

npm run build
npm run test
npm run inspector

パッケージの確認

npmの機能で公開前にパッケージの確認をできます。

公開予定のプロジェクト内でローカルでパッケージを見れるようにする
npm link

使う側のプロジェクト内でパッケージの参照を追加
npm link sample-project
使う側のプロジェクト内で動作確認後に参照を削除
npm unlink sample-project

公開予定のプロジェクト内でローカルでのパッケージを除去
npm unlink

npmへの公開手順

npmにアカウントを作ってトークンを発行しておきます。

最初にloginします。

npm login

公開前の再確認のため、--dry-runのオプションを付けて実施します。出力内容を確認し、必要にに応じて修正します。

npm publish --dry-run

package.jsonに誤りがある場合は、以下実施するように言われるかもしれません。

npm pkg fix

ここまで問題がなければ、npmへのパッケージ公開を行います。

npm publish

npxでの動作確認

公開がうまくできていれば以下で動作確認ができます。

npx @modelcontextprotocol/inspector npx -y sample-project
# npx @modelcontextprotocol/inspector node path\to\sample-project\build\index.js

クライアントでの設定は以下のようになります。

"sample-project": {
  "command": "npx",
  "args": [
    "-y",
    "sample-project"
  ]
}

実際のサンプル

以下コードのサンプルです。

npxメモ

npxで実行されるコマンド

npxでは、package.jsonにあるbinのコマンドが呼ばれます。

"bin": {
  "sample-project": "build/index.js"
},

shebang

index.ts(とindex.js)の先頭にあるshebangを間違って消してしまうと動かないようです。

#!/usr/bin/env node

/**
 * This is a template MCP server that implements a simple notes system.