A TypeScript-based project featuring a lightweight filesystem server and an interactive AI agent that can read, write, search, and list files through natural language conversation.
概览
A TypeScript-based project featuring a lightweight filesystem server and an interactive AI agent that can read, write, search, and list files through natural language conversation. This project consists of communicating via the MCP protocol: A filesystem tool server that exposes over MCP via stdio transport: - 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 (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 - (v18+ recommended) - - An (get one at openrouter.ai) 4. (optional — orchestrator spawns it automatically) 6. — Type natural language commands like: - "List all files in the src directory" - "Read the contents of package.
README
以下为原文 README 节选，完整内容请查看原文。
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
安装
This server does not publish a one-line install command.
Open the repository installation guide 新手？先看 mcpskill.org 教程 →