Filesystem SSE Server in Go

Filesystem MCP

このリポジトリは、ディレクトリ内の項目の一覧表示、ファイルの読み書き、ファイル情報の取得、ファイルやディレクトリの名前変更とコピーなど、ファイルシステムを操作するためのツール一式を提供する MCP の実装です。

ローカルマシンで、stdio または SSE サーバーとして実行できます。

目次

• インストール
  • リポジトリをクローンしてローカルにインストール
  • Docker を使用する
• 使い方
  • Python の PydanticAI での使用例
    • SSE サーバーを使用する
    • stdio を使用する
• ツールの説明

インストール

1. システムに Go がインストールされていることを確認してください。Go バージョン 1.24 を使用してください。
2. 次のコマンドを実行して、go install でパッケージをインストールします。

go install github.com/lealre/fs-mcp@latest

3. ヘルプコマンドを実行します。

fs-mcp -h

• -dir フラグは、サーバーが公開するベースディレクトリを指定します。必須です。
• -port フラグは、サーバーがリッスンするポートを指定します。省略可能で、デフォルトは 8080 です。
• -t フラグは、トランスポートの種類を指定します。stdio または http を指定できます（デフォルトは stdio です）。

リポジトリをクローンしてローカルにインストール

1. リポジトリをローカルマシンにクローンします。

git clone https://github.com/lealre/fs-mcp.git

2. クローンしたディレクトリに移動します。

cd fs-mcp

3. プロジェクトをビルドします。

go build

4. 実行可能ファイルを実行します。

./fs-mcp -t http -dir /your/directory/path

• これにより、サーバーが http://localhost:8080 で起動します。

Docker を使用する

この MCP は、SSE オプションを使用して Docker でのみ実行できます。そのためには、ファイルシステム操作で公開するディレクトリを指すボリュームを作成してください。

Docker Hub からイメージを取得して、次のように実行できます。

docker pull lealre/fs-mcp:latest

または、クローンしたリポジトリからイメージをビルドします。

docker build -t fs-mcp .

コンテナを実行し、任意のディレクトリとポートをマッピングします。

docker run -p 8080:8080 -v /your/directory/path:/baseDir lealre/fs-mcp -volume "/your/directory/path:/baseDir"

• /your/directory/path を、実際に公開するパスに置き換えてください。
• -p フラグは、ローカルマシンのポートを Docker コンテナのポートにマッピングします。
• -v フラグは、--volume フラグと同様にベースディレクトリのパスを指定し、Docker がファイルにアクセスできるようにします。

この設定により、指定したディレクトリを公開するサーバーが http://localhost:8080 で起動します。

重要

正しく動作させるには、-v と -volume のパスが完全に一致していることを確認してください。

コンテナのベースフォルダのボリューム名（/baseDir）は変更できます。また、-port フラグを使用してポートを変更できます（Docker の -p も合わせて調整してください）。例：

docker run -p 8081:8081 -v /your/directory/path:/baseDir lealre/fs-mcp -volume "/your/directory/path:/baseDir" -port 8081

使い方

インストールが完了したら、次のコマンドを実行してサーバーを使用できます。

fs-mcp -t http -dir /your/directory/path

これにより、MCP サーバーが http://localhost:8080 で起動し、ファイルシステム操作をこの特定のパス配下に制限します。

現時点では、サーバーに指定できるパスは 1 つだけです。

サーバーのポートを変更するには、フラグとして渡します。

fs-mcp -dir /your/directory/path -port 3000

stdio で実行するには、-t フラグを省略してください。

Python の PydanticAI での使用例

SSE サーバーを使用する

• MCP サーバーを実行します。

fs-mcp -dir /your/directory/path

• Python クライアントを作成します（ここでは OpenAI を使用します）。

# script.py

import asyncio
import sys
from pydantic_ai import Agent
from pydantic_ai.mcp import MCPServerSSE

server = MCPServerSSE('http://localhost:8080/sse')
agent = Agent('openai:gpt-4o', mcp_servers=[server])

async def main():
    if len(sys.argv) < 2:
        print("Usage: python script.py 'your prompt/query here'")
        sys.exit(1)

    query = sys.argv[1]

    async with agent.run_mcp_servers():
        result = await agent.run(query)

    print(result.output)

if __name__ == '__main__':
    asyncio.run(main())

• その後、次のコマンドを実行します。

python script.py "List all the entries for the path in /your/directory/path/somesubpath"

stdio を使用する

• Python クライアントを作成します（ここでは OpenAI を使用します）。

# script.py

import asyncio
import sys
from pydantic_ai import Agent
from pydantic_ai.mcp import MCPServerStdio

base_path = "/your/directory/path"
server = MCPServerStdio(
    'fs-mcp',
    args=['-dir', base_path]
)
agent = Agent('openai:gpt-4o', mcp_servers=[server])

async def main():
    if len(sys.argv) < 2:
        print("Usage: python script.py 'your prompt/query here'")
        sys.exit(1)

    query = sys.argv[1]

    async with agent.run_mcp_servers():
        result = await agent.run(query)

    print(result.output)

if __name__ == '__main__':
    asyncio.run(main())

• その後、次のコマンドを実行します。

python script.py "List all the entries for the path in /your/directory/path/somesubpath"

ツールの説明

このプロジェクトでは、ファイルシステムを操作するさまざまなツールを提供しています。各ツールの説明は以下のとおりです。

• listEntries：指定したパスにあるエントリーを一覧表示します。パラメーター：

  • path（string、必須）：すべてのエントリーを一覧表示するパス。
  • depth（number、任意）：ディレクトリツリーの深さ（デフォルトは3）。

• readFromFile：指定したパスにあるファイルの内容を読み取ります。パラメーター：

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

• writeToFile：指定した内容でファイルを作成または上書きします。パラメーター：

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

• getFileInfo：サイズ、最終更新時刻、検出されたMIMEタイプ、ファイル権限などのファイル情報を取得します。パラメーター：

  • path（string、必須）：情報を取得するファイルのパス。

• renamePath：ファイルまたはディレクトリの名前を変更します。パラメーター：

  • path（string、必須）：名前を変更するファイルまたはディレクトリのパス。
  • newPathFinalName（string、必須）：ファイルまたはディレクトリの新しい名前（フルパスではなく、名前のみ）。

• copyFileOrDir：ファイルまたはディレクトリを新しい場所にコピーします。パラメーター：

  • path（string、必須）：コピーするファイルまたはディレクトリのパス。
  • destination（string、必須）：ファイルまたはディレクトリのコピー先パス。

このプロジェクトでは、コア機能の実装にmcp-go libraryを使用しています。