- MCP Server Filesystem Service
MCP Server Filesystem Service
This repository implements a highly scalable filesystem service for the MCP server. It provides functionalities such as:
- Validating and normalizing file paths
- Reading, writing, and editing files with support for caching
- Searching files by patterns
- Creating directory trees and listing directories
- Enforcing security limits (e.g., maximum file size, allowed directories)
Table of Contents
- Overview
- Installation
- Usage
- Testing
- Development Workflow
- CI/CD Pipelines
- Making Changes to Tests
- Contributing
Overview
The Filesystem Service is built using TypeScript and Node.js. It is designed to:
- Ensure DRY code following 12-factor app and AWS well-architected principles.
- Handle file operations securely by validating paths against allowed directories.
- Cache file contents for improved performance.
- Provide diff-based file editing with flexible matching.
Installation
- Clone the repository:
git clone https://github.com/your-repo/mcp-server-filesystem.git
cd mcp-server-filesystem
- Install dependencies:
make install
Usage
Running Locally
To build and run the service locally:
- Build the project:
make build-local
- Run the service:
npm start
or, if you prefer:
node dist/index.js
Docker & Production
- Build the Docker image:
make build
- Run the container (with a workspace mounted):
make run
- For development mode (with Docker Compose):
make dev
- For production mode (with Docker Compose):
make prod
Testing
This project uses Jest for testing.
- Run unit tests:
make test
- Run tests in watch mode:
make test-watch
- Generate test coverage report:
make test-coverage
Test fixtures are set up in the tests/__fixtures__
directory. To update tests or add new ones, modify files under tests/
and run the tests using the above commands.
Development Workflow
- Install dependencies:
make install
- Build the project:
make build-local
- Run the TypeScript compiler in watch mode:
make watch
- Lint and format code:
make lint
make format
CI/CD Pipelines
GitLab CI
The GitLab pipeline is defined in .gitlab-ci.yml
and includes stages for:
- Linting: Both TypeScript and Python lint checks.
- Building: Docker image building and pushing.
- Testing: Running unit and integration tests.
- Security: Running Snyk tests and npm audit.
- Versioning & Release: Running version management scripts.
- Cleanup: Pruning Docker resources.
GitHub Actions
A GitHub Actions workflow is provided in .github/workflows/ci.yml
that mirrors the GitLab pipeline. It includes jobs for linting, building, testing, security scanning, versioning, and cleanup.
Making Changes to Tests
- All tests are located in the
tests/
directory. - Update test fixtures in
tests/setup.ts
if you modify how files/directories are structured. - Run tests locally using:
make test
- For coverage, run:
make test-coverage
Contributing
Feel free to open issues or pull requests. When contributing:
- Follow the coding style and best practices.
- Update tests to cover any new functionality.
- Ensure that the CI/CD pipeline passes on both GitLab and GitHub Actions.