Skip to main content
Glama
midsane

MCP Filesystem Server

by midsane
OverviewSchemaSourceRelated ServersDiscussionsAdmin
TypeScript
Local

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     ││  │
│                          └─────────────────────┘│  │
└─────────────────────────────────────────────────────┘

Related MCP server: ai-distiller-mcp

📦 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

This server cannot be deployed

One endpoint for every MCP toolRayrun runs every MCP server behind one URL and holds the credentials. Each call is decided per client, tool, and argument, then recorded.ray.runAd

Maintenance

ActivityInactive
ResponsivenessNo issues

Resources

Related MCP Connectors

Related MCP Servers

  • maic-server-fs-mcp

    maicFir
    A
    license
    A
    quality
    D
    maintenance
    Provides LLMs with local filesystem operations (read/write files, list directories) and command execution via MCP, enabling file management and task automation within AI clients.
    7
    14 npm
    ISC

  • filezop

    Jefreesujit
    A
    license
    Not graded
    quality
    D
    maintenance
    Exposes file system operations to AI clients via MCP, enabling secure read, write, and management of files and folders.
    3 npm
    MIT

Appeared in Searches