Skip to main content
Glama
Sign In
MCP Filesystem Server

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: maic-server-fs-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

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections.

Loading tool schema changelog…

    This server cannot be deployed

    Claude Code, inside the Godot 4 editorFlockbay puts an AI agent in the real Godot 4 editor: it writes GDScript, runs your game and fixes what breaks. Free, or bring your own Claude Code or Codex.flockbay.comAd

    Maintenance

    ActivityInactive
    ResponsivenessNo recent community 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
      15 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.
      2 npm
      MIT

    • Filesystem MCP Server

      kaustubhwarke
      F
      license
      Not graded
      quality
      D
      maintenance
      Enables AI agents to interact with a sandboxed filesystem via MCP tools for reading, writing, searching, and monitoring files, including batch processing and resource discovery for resume management.
      -

    Appeared in Searches