parfaitBashombe/mcp-server

MCP Codebase Server

A production-ready Model Context Protocol (MCP) server that enables AI assistants to read, understand, and modify your codebase safely and efficiently.

Features

• FileSystem Operations: Read, write, delete, move files, and create directories.
• Codebase Analysis: Generates summaries of project structure, dependencies, and frameworks.
• Smart Ignore: Respects .gitignore and configures default ignore patterns (node_modules, etc.) to avoid processing unnecessary files.
• Security: Prevents path traversal and enforces workspace boundaries to keep your system safe.
• Type-Safe: Built with a full TypeScript implementation for reliability.

Prerequisites

• Node.js: Version 18 or higher.
• pnpm: Recommended package manager (or npm/yarn).

Installation

1. Clone the repository:

   git clone <repository-url>
   cd mcp-server
   

2. Install dependencies:

   pnpm install
   

3. Build the project:

   pnpm run build
   

Configuration

The server can be configured using environment variables:

• WORKSPACE_PATH: (Optional) The absolute path to the workspace directory you want the AI to access. If not provided, it defaults to the current working directory where the server is started.

Usage

Running the Server

To start the server via stdio (standard input/output):

node dist/index.js

Or with a specific workspace:

WORKSPACE_PATH=/path/to/your/project node dist/index.js

Connecting to Claude Desktop

To use this server with Claude Desktop, add the following configuration to your claude_desktop_config.json (usually located at ~/Library/Application Support/Claude/claude_desktop_config.json on macOS):

{
  "mcpServers": {
    "codebase": {
      "command": "node",
      "args": [
        "/absolute/path/to/mcp-server/dist/index.js"
      ],
      "env": {
        "WORKSPACE_PATH": "/absolute/path/to/target/workspace"
      }
    }
  }
}

Replace /absolute/path/to/mcp-server with the actual path to this project, and /absolute/path/to/target/workspace with the directory you want Claude to work on.

Available Tools

The server exposes the following tools to the AI:

• read_file: Read the complete contents of a file.
  • path: Relative path to the file.
• write_file: Create or overwrite a file.
  • path: Relative path to the file.
  • content: Content to write.
• delete_file: Delete a file or directory.
  • path: Relative path to the file/directory.
• list_files: List the file structure of a directory (tree view).
  • path: Directory path (default: root).
• search_files: Search for files matching a glob pattern.
  • pattern: Glob pattern (e.g., **/*.ts).
• create_directory: Create a new directory (recursive).
  • path: Directory path.
• move_file: Move or rename a file.
  • source: Current path.
  • destination: New path.
• get_codebase_summary: Analyze the codebase and return a summary including project info, dependencies, and file structure.

Development

• Watch mode: Rebuilds on file changes.

  pnpm run watch
  

• Dev mode: Builds and runs the server.

  pnpm run dev
  

License

MIT