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
  • Running Locally
  • Docker & Production
• Testing
• Development Workflow
• CI/CD Pipelines
  • GitLab CI
  • GitHub Actions
• 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

1. Clone the repository:

git clone https://github.com/your-repo/mcp-server-filesystem.git
cd mcp-server-filesystem

2. Install dependencies:

make install

Usage

Running Locally

To build and run the service locally:

1. Build the project:

make build-local

2. Run the service:

npm start

or, if you prefer:

node dist/index.js

Docker & Production

1. Build the Docker image:

make build

2. Run the container (with a workspace mounted):

make run

3. For development mode (with Docker Compose):

make dev

4. 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.