source-sage

SourceSage MCP is a server that visualizes a project's directory structure in Markdown, automatically documents file contents with syntax highlighting, and supports flexible ignoring via .SourceSageignore. It exposes a tool called generate_structure that traverses a given project directory and outputs a detailed, human- and machine-readable representation of the project, including a tree view and per-file details. This enables you to quickly grasp the full project layout and contents from a single, generated document. To use it, configure the MCP server with the source-sage instance and call the generate_structure tool through the MCP client, passing the absolute path to the target project and, optionally, the absolute path to a .SourceSageignore file to control exclusions. The server leverages modern Node.js features and standard libraries like glob and ignore to efficiently walk large codebases while respecting your ignore patterns.

Prerequisites:

• Node.js (v16 or later) and npm installed on your system
• Access to the internet to install packages

Install globally from npm:

npm install -g @sunwood-ai-labs/source-sage-mcp-server

Alternatively, clone the repository and build from source:

git clone https://github.com/sunwood-ai-labs/source-sage-mcp-server.git
cd source-sage-mcp-server
npm install
npm run build

Configure MCP to run the server (example in mcp.json or equivalent):

{
  "mcpServers": {
    "source-sage": {
      "command": "node",
      "args": ["C:/path/to/source-sage/build/index.js"]
    }
  }
}

Start the MCP server according to your environment (use your platform's typical Node.js startup procedure).

Tips and common issues:

• Ensure the path in the mcpServers config points to a valid built entry (e.g., build/index.js) if you compile from TypeScript.
• Use absolute paths for both the target project and the .SourceSageignore file when invoking generate_structure to avoid path resolution issues.
• The default ignore patterns can be extended or overridden via a .SourceSageignore file in the target project root.
• If you encounter permission or path errors on Windows, verify that your path strings use forward slashes or escaped backslashes and that Node.js has access to the directories.
• The MCP server uses ES2022 features and Node16 module system; ensure your environment matches these requirements for best compatibility.
• For large projects, consider running generate_structure in batches or with a tailored ignore list to improve performance.