Filesystem MCP Assistant

This project upgrades the original milestone 1 filesystem helper approach to an MCP-based architecture.

What changed

• The filesystem business logic now lives in a shared domain layer.

• mcp_filesystem_server.py exposes the functionality through MCP-style JSON-RPC methods.

• llm_file_assistant.py talks to the filesystem through an MCP client wrapper instead of importing direct helpers.

• Batch processing and watch sessions are exposed as MCP tools.

• Resource discovery is exposed through MCP resources and resource templates.

Related MCP server: Filesystem MCP Server

Setup

python -m venv .venv
.\.venv\Scripts\Activate.ps1
pip install -r requirements.txt

Set your model credentials in .env or environment variables:

OPENROUTER_API_KEY=your_key_here
OPENROUTER_MODEL=openai/gpt-4o-mini
OPENROUTER_HTTP_REFERER=http://localhost
OPENROUTER_APP_NAME=Filesystem MCP Assistant

Run

Generate sample resumes:

python generate_mock_data.py

Start the agent:

python llm_file_assistant.py

Run the test suite:

pytest

MCP workflow

stateDiagram-v2
    [*] --> Agent
    Agent --> MCPClient: list tools/resources
    MCPClient --> MCPServer: initialize + JSON-RPC request
    MCPServer --> MCPClient: tool/resource result
    MCPClient --> Agent: structured result
    Agent --> Model: tool message + context
    Model --> Agent: final answer or another tool call
    Agent --> [*]: task complete

Test scenarios

• Resource discovery returns capabilities and resource templates.

• watch_directory reports new resume files after a second poll.

• batch_process can read or search multiple resumes in one call.

• The agent can resolve a tool call through MCP and produce a final response.

• The end-to-end flow works with a real MCP subprocess and a stubbed model response.