MCP Filesystem Server & AI Orchestrator

A TypeScript-based Model Context Protocol (MCP) project featuring a lightweight filesystem server and an interactive AI agent that can read, write, search, and list files through natural language conversation.

---

🏗️ Architecture

This project consists of two main components communicating via the MCP protocol:

┌─────────────────────────────────────────────────────┐
│                  AI Orchestrator                     │
│            (src/orchestrator.ts)                     │
│                                                     │
│  ┌──────────┐   ┌──────────┐   ┌─────────────────┐  │
│  │  User    │──▶│  OpenAI  │──▶│  MCP Client     │  │
│  │  Input   │   │  (LLM)   │   │  (Stdio)        │  │
│  └──────────┘   └────┬─────┘   └────────┬────────┘  │
│       ▲              │                   │          │
│       │         tool calls          tool results    │
│       │         & responses              │          │
│  ┌────┴────┐                            │          │
│  │  Output │                            ▼          │
│  └─────────┘                      ┌──────────────┐  │
│                                   │              │  │
│                          ┌─────────────────────┐│  │
│                          │  MCP Filesystem     ││  │
│                          │  Server             ││  │
│                          │  (src/index.ts)     ││  │
│                          │                     ││  │
│                          │  • list_files       ││  │
│                          │  • read_file        ││  │
│                          │  • write_file       ││  │
│                          │  • search_files     ││  │
│                          └─────────────────────┘│  │
└─────────────────────────────────────────────────────┘

---

📦 Tech Stack

Technology	Purpose
TypeScript	Language
tsx	Run TypeScript directly (no build step)
Node.js	Runtime
@modelcontextprotocol/sdk	MCP protocol implementation
OpenAI SDK	LLM communication via OpenRouter
zod	Runtime validation
dotenv	Environment variable management

---

🔧 Components

1. MCP Server — src/index.ts

A filesystem tool server that exposes 4 tools over MCP via stdio transport:

Tool	Description	Parameters
list_files	List files in a directory	dir (string) — required
read_file	Read contents of a file	filePath (string) — required
write_file	Write content to a file	filePath (string), content (string) — both required
search_files	Search files containing specific text	dir (string), query (string) — both required

2. Orchestrator / AI Agent — src/orchestrator.ts

An interactive AI agent that:

• Connects to the MCP server (spawns it as a child process)
• Dynamically fetches available tools from the server
• Accepts natural language user input via a REPL interface
• Sends prompts to the OpenAI-compatible LLM (inclusionai/ring-2.6-1t:free via OpenRouter)
• Detects tool call requests in the model's response
• Executes the corresponding MCP tools on the server
• Feeds tool results back to the model for continued reasoning
• Outputs the final natural language answer

---

🔄 Interaction Flow

 User Input
      │
      ▼
┌──────────────┐
│  OpenAI LLM  │  (via OpenRouter)
│  (Reasoning) │
└──────┬───────┘
       │
   ┌───┴────────┐
   │ Tool Call?  │
   └───┬────────┘
   Yes │        No
       ▼          ▼
┌────────────┐  ┌──────────────┐
│ MCP Server │  │  Final Answer│
│ (File Ops) │  │  → User      │
└─────┬──────┘  └──────────────┘
      │
      ▼
  Tool Result
      │
      ▼
  Feed back to LLM → Continue reasoning or finalize

---

⚡ Quick Start

Prerequisites

• Node.js (v18+ recommended)
• npm
• An OpenRouter API key (get one at openrouter.ai)

Setup

1. Clone the repository

   git clone <repo-url>
   cd mcp
   

2. Install dependencies

   npm install
   

3. Configure environment variables

   cp sample-env .env
   # Edit .env and add your OpenRouter API key:
   # OPENROUTER_API_KEY=your_key_here
   

4. Start the MCP Server (optional — orchestrator spawns it automatically)

   npm run dev
   

5. Run the Orchestrator

   npm run orchestrator
   

6. Interact with the agent — Type natural language commands like:

   • "List all files in the src directory"
   • "Read the contents of package.json"
   • "Write a hello world message to a new file"
   • "Search for 'import' in the src folder"
   • Type exit to quit

---

📁 Project Structure

.
├── .env                    # OpenRouter API key (not committed)
├── .gitignore              # Git ignore rules
├── package.json            # Node.js project configuration
├── package-lock.json       # Dependency lock file
├── sample-env              # Environment variable template
├── tsconfig.json           # TypeScript compiler options
├── README.md               # This file
└── src/
    ├── index.ts            # MCP Server — filesystem tools
    └── orchestrator.ts     # AI Agent — MCP client & prompt loop

---

📝 Notes

• Model: The orchestrator uses inclusionai/ring-2.6-1t:free via OpenRouter. This can be changed in src/orchestrator.ts by modifying the model field in the chat.completions.create() call.
• Transport: Both server and client communicate over stdio (StdioServerTransport / StdioClientTransport), which is the simplest MCP transport method.
• Security: This is a demo project. In production, you'd want proper error handling, input validation, security boundaries on file access, and potentially a different transport method (e.g., SSE or HTTP).

---

📚 References

• Model Context Protocol (MCP)
• MCP SDK
• OpenRouter
• OpenAI Node.js SDK