Skip to main content
Glama
midsane

MCP Filesystem Server

by midsane
OverviewSchemaRelated ServersScoreDiscussions
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     ││  │
│                          └─────────────────────┘│  │
└─────────────────────────────────────────────────────┘

📦 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 installed

A
license - permissive license
-
quality - not tested
C
maintenance

How are these scores calculated?

Resources

Unclaimed servers have limited discoverability.

Looking for Admin?

If you are the server author, to access and configure the admin panel.

Latest Blog Posts

MCP directory API

We provide all the information about MCP servers via our MCP API.

curl -X GET 'https://glama.ai/api/mcp/v1/servers/midsane/mcp'

If you have feedback or need assistance with the MCP directory API, please join our Discord server