Local Project Sync

You enable your local codebase to be queried and analyzed by MCP-enabled AI apps. This server connects directly to your local project, turning it into a dynamic knowledge base that AI can inspect in real time without uploading files to the cloud.

How to use

You interact with the local MCP server through an MCP client. Start the local server, then configure your client to connect to it. Once connected, you can explore your project structure, read specific files, and perform intelligent searches across your codebase. Use the provided tools to extract complete function definitions, read targeted file sections, and batch-read multiple files for module-level context.

Typical usage flows include discovering the project layout, performing targeted searches for classes or functions, extracting full definitions with surrounding comments and decorators, and then inspecting related files to build a coherent view of how components interact. Context lines can be requested to avoid overwhelming results, and you can filter by file type to keep results focused.

How to install

Prerequisites: you need Node.js and a package manager installed on your system.

Step 1: Clone the project repository.

git clone https://github.com/cytrogen/mcp-local-sync.git
cd mcp-local-sync

Step 2: Install dependencies.

npm install

# or

yarn install

Step 3: Configure synchronization paths. Edit the TypeScript source to set the absolute paths you want to sync. Then build the project.

const SYNC_PATHS = [
  "D:\\your\\project\\directory\\src",
  "D:\\another\\project\\directory\\src"
];

Step 4: Build the project to generate the runtime indexer.

npm run build

# or

yarn run build

Configuration and running

To connect the local MCP server to your AI client, add a local stdio MCP server configuration. This runs the Node process that serves the MCP endpoints directly from your machine.

Example configuration for the client to launch the local server. Replace the path with the actual location of your built index file.

{
  "mcpServers": {
    "local_project_sync": {
      "command": "node",
      "args": [
        "D:\\path\\to\\your\\mcp-local-sync\\build\\index.js"
      ]
    }
  }
}

Notes and best practices

Security: grant read access only to directories that contain your project code. Avoid syncing sensitive directories that hold keys or secrets.

Performance: initial scans of large workspaces can take longer. You can narrow scope with file type filters and targeted queries to improve responsiveness.

Path formats: when you interact with the AI, prefer using the full file paths returned by the tools to ensure precise tool invocations.

Build and start: ensure you have built the project before attempting to run the MCP server locally. Use the runtime command shown in the configuration example to start the server.

Available tools

list_project_files

Recursively lists all files in the configured directories to provide a full view of the project.

read_file_content

Reads the complete content of a single specified file for deep code analysis.

analyze_project_structure

Generates an overview and statistics of the project structure to help you quickly understand the project.

search_code_content

Performs intelligent search across the codebase with text and regex options, contextual lines, directory scoping, and result limits.

read_multiple_files

Reads multiple files in bulk using glob patterns to provide module-level context.

extract_function_definition

Extracts the full definition of a specified function or method, including comments and decorators.

read_file_section

Reads a specific range of lines from a file to obtain precise code snippets.