Tela

tela-mcp

Tela インスタンスに組み込まれた MCP サーバー向けのシンプルな stdio↔HTTP プロキシです。

v0.7 以降、MCP サーバーは Tela バックエンド内の {TELA_BASE_URL}/api/mcp にあります（仕様に準拠した Streamable HTTP）。この npm パッケージは 独自のツールを実装しなくなりました。ツール、リソース、プロンプト、通知を含む MCP プロトコル全体を、 stdio 経由でそのエンドポイントに転送するだけのシンプルなパイプです。その際、個人用アクセス トークンをベアラーヘッダーとして付与します。ツールに関する知識を持たないため、バックエンドの MCP 機能を拡張しても、このパッケージを変更する必要はありません。二重の実装が乖離する心配もありません。

ほとんどのホストではこのパッケージは不要です

最新の MCP ホストは Streamable HTTP トランスポートを直接利用できます。エンドポイントを指定するだけで、 プロキシを介さずに接続できます。

# Claude Code
claude mcp add --transport http tela https://telawiki.com/api/mcp \
  --header "Authorization: Bearer tela_pat_..."

Cursor、VS Code、Zed、および Anthropic Messages API の mcp_servers コネクターも、 URL とベアラーヘッダーを受け付けます。この npm パッケージは、HTTP トランスポートを利用できない stdio 専用ホストでのみ使用してください。

プロキシの使用方法（stdio 専用ホスト）

.mcp.json に追加します。

{
  "mcpServers": {
    "tela": {
      "command": "npx",
      "args": ["-y", "tela-mcp@latest"],
      "env": {
        "TELA_BASE_URL": "https://telawiki.com",
        "TELA_API_KEY": "tela_pat_..."
      }
    }
  }
}

変数	用途
TELA_BASE_URL	Tela インスタンスのオリジン（例：https://telawiki.com または http://localhost:8780）。プロキシは {TELA_BASE_URL}/api/mcp に接続します。
TELA_API_KEY	個人用アクセス トークン（tela_pat_…）。Authorization: Bearer として転送されます。Settings → API Keys で作成してください。

MCP ハンドシェイクの前にプロセスがゼロ以外の終了コードで終了しないよう、起動時に両方を設定する必要があります。

ツールとリソースの一覧

ツール（list_spaces、get_page、search、semantic_search、 create_page、move_page、add_comment、…）、tela://page/{id} / tela://space/{id} リソース、および読み取り／書き込み／管理のスコープモデルはすべて、 ここではなくバックエンドで定義、ドキュメント化されています。スコープとスペースごとの 制限はサーバー側で適用されます。エラーはツールの結果に通常の {error, code, status} エンベロープとして返されます。プロジェクトのショーケースをご覧ください： https://telawiki.com/spaces/1/pages/19。

認証

このパッケージは静的な個人用アクセス トークン（PAT）で認証します。これは Messages API コネクターや、 ベアラーヘッダーを受け付けるすべてのホストで使用できます。 Claude.ai／ChatGPT のコンシューマーアプリで使われる OAuth の「Connect」フローは別個の サーバー側機能であり、このパッケージは関与しません。

開発

cd mcp
npm install
npm run build            # tsc → dist/server.js
npm run test:integration # live proxy↔backend E2E (needs a running backend; use `make test-mcp-integration` from the repo root)

このプロキシは、公式の @modelcontextprotocol/sdk トランスポートを使った約 40 行の実装です。 ツールごとの網羅的なテストは、Go バックエンドの e2e MCP テスト （backend/internal/api/mcp_test.go）にあります。

ライセンス

AGPL-3.0-only。