ylcnfrht/file-mcp-server

File MCP Server

A tiny Model Context Protocol (MCP) server that exposes basic file system operations. Built with TypeScript and Zod. Easy to extend.

Quick Start

npm install
npm run build && npm start

Server runs over stdio and operates on files within the current working directory (or FILE_BASE_DIR environment variable).

Development

npm run dev

Inspector

Interactive testing with MCP Inspector:

npm run build
npm run inspector

This starts the server under the inspector so you can list tools and call them.

Tools

• listFiles: lists all files in a directory
• readFile: reads the content of a file
• writeFile: writes content to a file (creates or overwrites)
• deleteFile: deletes a file from the filesystem

List tools request (MCP):

{
  "method": "tools/list",
  "params": {}
}

Call example:

{
  "method": "tools/call",
  "params": {
    "name": "writeFile",
    "arguments": { "filePath": "example.txt", "content": "Hello, World!" }
  }
}

Response example:

{
  "content": [{ "type": "text", "text": "File \"example.txt\" written successfully." }]
}

Validation & Schemas

• Input validation is done with Zod directly in src/index.ts.
• inputSchema returned by tools/list is a JSON Schema object that MCP clients can use.

File path input schema (Zod):

const readInput = z.object({ filePath: z.string().describe('Path to the file to read') });

File path and content input schema (Zod):

const writeInput = z.object({
  filePath: z.string().describe('Path to the file to write'),
  content: z.string().describe('Content to write'),
});

JSON Schema (for MCP):

const inputFilePathAndContentJsonSchema = {
  type: 'object',
  properties: {
    filePath: { type: 'string', description: 'filePath' },
    content: { type: 'string', description: 'content' },
  },
  required: ['filePath', 'content'],
} as const;

Project Structure

src/
  index.ts   # server setup, tool definitions, validation, and handlers
dist/
  index.js   # build output

Extending (add a new tool)

All tools are defined in src/index.ts under the tools map. To add one:

1. Add or reuse a Zod schema and corresponding JSON Schema.
2. Implement an execute function.
3. Register the tool in the tools map with description, inputSchema, validate, execute, and format.

Scripts

From package.json:

• build: compile TypeScript to dist/
• start: run node dist/index.js
• dev: tsc && node dist/index.js
• inspector: npx @modelcontextprotocol/inspector node dist/index.js

Troubleshooting

• "Cannot find module …/x.js": ensure ESM paths include .js extensions (tsconfig uses NodeNext).
• "File not found": readFile throws when file doesn't exist.
• "Invalid arguments …": Zod validation failed; ensure valid filePath and content strings.
• "Permission denied": ensure the server has read/write permissions for the target directory.

License

MIT