STeLA MCP

STeLA MCP

標準化された API インターフェースを通じて、ローカルシステムの操作に安全にアクセスできる Model Context Protocol サーバーの Python 実装です。

STeLA（Simple Terminal Language Assistant）MCP は、標準化された API インターフェースを通じて、ローカルマシンのコマンドやファイル操作に安全にアクセスできる軽量サーバーです。アプリケーションとローカルシステムをつなぐブリッジとして機能し、Model Context Protocol（MCP）アーキテクチャを実装しています。

概要

STeLA MCP は、Model Context Protocol（MCP）アーキテクチャを実装し、アプリケーションがローカルマシン上でコマンドを実行したり、ファイル操作を行ったりするための、安全で標準化された方法を提供します。明確に定義された API を通じてリクエストを受け付け、制御された環境で操作を実行し、整形した結果を返す仲介レイヤーとして機能します。

機能

• コマンド実行：適切なエラー処理を行いながら、ローカルシステムでシェルコマンドを実行
• ファイル操作：ローカルシステム上のファイルの読み取り、書き込み、管理
• ディレクトリの可視化：ファイルシステムの再帰的なツリービューを生成
• 作業ディレクトリのサポート：特定のディレクトリでコマンドを実行
• 堅牢なエラー処理：詳細なエラーメッセージと検証
• 包括的な出力：標準出力と標準エラー出力の両方を取得して返却
• シンプルな統合：さまざまなクライアントと簡単に統合できる標準入出力インターフェース
• 複数ディレクトリのサポート：ファイル操作を許可する複数のディレクトリを設定
• セキュリティ優先の設計：厳格なパス検証とコマンド実行の制御
• ファイル検索：パターンに一致するファイルを検索
• ファイル編集：ファイルの一部を選択して編集
• 型安全性：すべてのツール入力を Pydantic モデルで厳密に型チェック
• パス検証：シンボリックリンクと親ディレクトリの検証を強化

インストール

Smithery 経由でのインストール

Smithery を使って、Claude Desktop 用に STeLA を自動でインストールするには：

npx -y @smithery/cli install @Sachin-Bhat/stela-mcp --client claude

前提条件

• Python 3.10 - 3.12
• pip または uv パッケージマネージャー
• Pydantic v2.x

インストール手順

1. リポジトリをクローンします：

git clone <repository-url>
cd stela-mcp

2. 仮想環境を作成して有効化します：

python -m venv .venv
source .venv/bin/activate  # On Windows: .venv\Scripts\activate

3. 依存関係をインストールします：

pip install -e .

バイナリ配布物の作成

自己完結型バイナリを作成するには：

1. PyInstaller をインストールします：

pip install pyinstaller

2. バイナリを作成します：

pyinstaller --onefile src/stella_mcp//server.py --name stela-mcp

バイナリは dist ディレクトリに作成されます。

設定

STeLA MCP は環境変数を使って設定できます：

ディレクトリアクセス制御

• ALLOWED_DIRS（必須）：ファイル操作を許可するディレクトリをカンマ区切りで指定

  • 例：/home/user/project,/home/user/docs
  • デフォルト：指定されていない場合は現在の作業ディレクトリ
  • 注：すべてのパスは絶対パスである必要があります

• ALLOWED_DIR（任意）：コマンド実行コンテキスト用のプライマリディレクトリ

  • 例：/home/user/project
  • デフォルト：ALLOWED_DIRS の先頭のディレクトリ、または現在の作業ディレクトリ
  • 注：これは ALLOWED_DIRS とは別の設定で、コマンド実行コンテキストを制御します

コマンド実行のセキュリティ

• ALLOWED_COMMANDS（任意）：許可するシェルコマンドをカンマ区切りで指定

  • 例：ls,cat,pwd,echo
  • デフォルト：ls,cat,pwd,echo
  • 特別な値：任意のコマンドを許可する all（非推奨）

• ALLOWED_FLAGS（任意）：許可するコマンドフラグをカンマ区切りで指定

  • 例：-l,-a,-h,--help
  • デフォルト：-l,-a,-h,--help
  • 特別な値：任意のフラグを許可する all（非推奨）

• MAX_COMMAND_LENGTH（任意）：コマンド文字列の最大長

  • 例：1024
  • デフォルト：1024
  • 注：長すぎる文字列を介したコマンドインジェクションを防ぎます

• COMMAND_TIMEOUT（任意）：コマンドの最大実行時間（秒）

  • 例：60
  • デフォルト：60
  • 注：コマンドのハングを防ぎます

設定例

# Directory access
export ALLOWED_DIRS="/home/user/project,/home/user/docs"
export ALLOWED_DIR="/home/user/project"

# Command execution
export ALLOWED_COMMANDS="ls,cat,pwd,echo"
export ALLOWED_FLAGS="-l,-a,-h,--help"
export MAX_COMMAND_LENGTH=1024
export COMMAND_TIMEOUT=60

プロジェクト構成

stela-mcp/
├── src/
│   ├── stela_mcp/
│   │   ├── __init__.py
│   │   ├── shell.py        # Shell command execution
│   │   ├── filesystem.py   # File system operations
│   │   └── security.py     # Security configuration
│   └── server.py           # Main server implementation
├── pyproject.toml          # Project configuration
└── README.md

使い方

サーバーの起動

次のコマンドでサーバーを起動します。

uv run python -m src.stella_mcp.server

サーバーが起動し、標準入出力を介して接続を待ち受けます。

Claude Desktop での使用

Claude Desktop で STeLA MCP を使用するには、次の手順に従います。

1. オプション 1：Python を直接使用する

   • 次のコマンドでサーバーを起動します。

     uv run python -m src.stela_mcp.server
     

   • Claude Desktop で、次の手順を実行します。
     • 「Settings」に移動します。
     • 「Tools」で「Add Tool」をクリックします。
     • 「MCP Server」を選択します。
     • 次の設定を入力します。
       • Name：STeLA MCP
       • Path：Python 実行ファイルの絶対パス（例：/home/username/.venv/bin/python）
       • Arguments：-m src.stela_mcp.server
       • Working Directory：STeLA MCP プロジェクトディレクトリのパス

2. オプション 2：バイナリを使用する

   • dist/stela-mcp からバイナリをコピーし、PATH に含まれる場所に配置します。
   • Claude Desktop で、次の手順を実行します。
     • 「Settings」に移動します。
     • 「Tools」で「Add Tool」をクリックします。
     • 「MCP Server」を選択します。
     • 次の設定を入力します。
       • Name：STeLA MCP
       • Path：バイナリの絶対パス（例：/usr/local/bin/stela-mcp）
       • Arguments：（空欄のままにします）
       • Working Directory：（空欄のままにします）

3. 設定が完了すると、Claude との会話で STeLA MCP ツールを使用できます。たとえば、次のように指示できます。

   • 「ホームディレクトリの内容を表示して」
   • 「内容を入力して、新しいファイル test.txt を作成して」
   • 「現在のディレクトリでコマンド ls -la を実行して」

4. Claude はリクエストに応じて適切なツールを自動的に使用し、結果を会話に表示します。

利用可能なツール

コマンドツール

execute_command

ローカルシステムでシェルコマンドを実行します。

パラメーター：

• command（string、必須）：実行するシェルコマンド
• working_dir（string、任意）：コマンドを実行するディレクトリ

戻り値：

• 成功時：コマンドの出力（stdout）
• 失敗時：エラーメッセージとコマンドの出力（stderr）

change_directory

現在の作業ディレクトリを変更します。

パラメーター：

• path（string、必須）：移動先のパス

戻り値：

• 成功時：新しいパスを含む成功メッセージ
• 失敗時：エラーメッセージ

ファイルシステムツール

read_file

ファイルの内容を読み取ります。

パラメーター：

• path（string、必須）：読み取るファイルのパス

戻り値：

• 成功時：ファイルの内容
• 失敗時：エラーメッセージ

read_multiple_files

複数のファイルを同時に読み取ります。

パラメーター：

• paths（array、必須）：読み取るファイルパスのリスト

戻り値：

• 成功時：すべてのファイルの内容を結合したもの
• 失敗時：エラーメッセージと部分的な結果

write_file

ファイルに内容を書き込みます。

パラメーター：

• path（string、必須）：ファイルの書き込み先のパス
• content（string、必須）：ファイルに書き込む内容

戻り値：

• 成功時：成功メッセージ
• 失敗時：エラーメッセージ

edit_file

ファイルを選択的に編集します。

パラメーター：

• path（string、必須）：編集するファイルのパス
• edits（array、必須）：編集操作のリスト
  • 各編集には oldText と newText が含まれます。
• dryRun（boolean、任意）：変更を適用せずにプレビューします。

戻り値：

• 成功時：変更の Git スタイルの差分
• 失敗時：エラーメッセージ

list_directory

ディレクトリの内容を一覧表示します。

パラメーター：

• path（string、必須）：一覧表示するディレクトリのパス

戻り値：

• 成功時：ファイルとディレクトリの一覧
• 失敗時：エラーメッセージ

create_directory

新しいディレクトリを作成します。

パラメーター：

• path（string、必須）：作成するディレクトリのパス

戻り値：

• 成功時：成功メッセージ
• 失敗時：エラーメッセージ

move_file

ファイルやディレクトリを移動または名前変更します。

パラメーター：

• source（文字列、必須）：移動するファイルまたはディレクトリの元のパス
• destination（文字列、必須）：ファイルまたはディレクトリの移動先のパス

戻り値：

• 成功時：成功メッセージ
• 失敗時：エラーメッセージ

search_files

パターンに一致するファイルを検索します。

パラメーター：

• path（文字列、必須）：検索を開始するパス
• pattern（文字列、必須）：ファイル名やディレクトリ名に一致させる検索パターン
• excludePatterns（配列、任意）：除外する glob パターンのリスト

戻り値：

• 成功時：一致するファイルのリスト
• 失敗時：エラーメッセージ

directory_tree

ファイルとディレクトリの再帰的なツリー表示を生成します。

パラメーター：

• path（文字列、必須）：ツリーを生成するディレクトリのパス

戻り値：

• 成功時：ディレクトリツリーを表す JSON 構造
• 失敗時：エラーメッセージ

get_file_info

ファイルやディレクトリの詳細なメタデータを取得します。

パラメーター：

• path（文字列、必須）：ファイルまたはディレクトリのパス

戻り値：

• 成功時：ファイル／ディレクトリのメタデータ
• 失敗時：エラーメッセージ

list_allowed_directories

サーバーがアクセスを許可されているすべてのディレクトリを一覧表示します。

パラメーター：

• なし

戻り値：

• 成功時：許可されたディレクトリのリスト
• 失敗時：エラーメッセージ

show_security_rules

現在のセキュリティ設定を表示します。

パラメーター：

• なし

戻り値：

• 成功時：セキュリティ設定の詳細
• 失敗時：エラーメッセージ

セキュリティに関する考慮事項

STeLA MCP は、ローカルシステム上でコマンドを実行し、ファイルを操作するための直接的なアクセスを提供します。以下のセキュリティ対策を検討してください。

• 適切な権限で実行してください（root／管理者としての実行は避けてください）
• 信頼できる環境でのみ使用してください
• 本番環境で使用する場合は、追加の認可メカニズムの実装を検討してください
• コマンドの実行やファイル操作を許可するディレクトリには注意してください
• システムファイルへの不正アクセスを防ぐため、パスの検証を実装してください
• ユースケースに応じて、可能な限り制限の厳しい設定を使用してください
• 許可するコマンドとディレクトリを定期的に確認し、更新してください
• 許可されたディレクトリ外へのアクセスを防ぐため、シンボリックリンクを検証してください
• ファイル作成操作では、親ディレクトリの確認を必ず行ってください

プラットフォーム固有のセキュリティに関する注意事項

Linux/macOS

• 権限を制限した専用ユーザーで実行してください
• ファイルシステムへのアクセスを制限するため、chroot 環境の使用を検討してください
• 実行権限を制限するには chmod を使用してください
• 追加のセキュリティ対策として SELinux/AppArmor の使用を検討してください

Windows

• 管理者ではなく、標準ユーザーとして実行してください
• アクセスを制限するため、Windows のセキュリティ機能の使用を検討してください
• 機密性の高いディレクトリへのアクセスを制限するには、フォルダー／ファイルの権限を使用してください
• Windows Defender Application Control の使用を検討してください

開発

新しいツールの追加

STeLA MCP に機能を追加するには、次の手順に従ってください。

1. server.py でツールの入力パラメーター用の Pydantic モデルを定義します
2. shell.py または filesystem.py の適切なクラスに新しいメソッドを追加します
3. @server.call_tool() デコレーターを使用して、server.py にツールを登録します
4. 適切なエラー処理と戻り値の型を備えたツールハンドラーを実装します

例：

from pydantic import BaseModel, Field

class MyToolInput(BaseModel):
    param1: str = Field(description="Description of param1")
    param2: int = Field(description="Description of param2")

@server.call_tool()
async def my_tool(request: Request[MyToolInput, str], arguments: MyToolInput) -> Dict[str, Any]:
    """Description of the tool."""
    try:
        # Tool implementation
        result = await do_something(arguments.param1, arguments.param2)
        return {"success": True, "result": result}
    except Exception as e:
        return {"error": str(e)}

ライセンス

Apache-2.0 ライセンス

謝辞

• MCP Python SDK を使用して構築