harmony-mcp

An MCP server that integrates your local workspace with the Harmony backend for codebase indexing and context retrieval. It exposes specialized tools to MCP clients (e.g. Claude Code, Claude Desktop, IntelliJ AI Assistant) over stdio.

Quick Start

Get started in seconds without configuring secrets manually.

1. Add the server to your MCP client config:

For Claude Code, run:

claude mcp add harmony -- npx -y @codeconductorai/harmony-mcp

Or add it directly to your client's config file (e.g., ~/.claude/claude_desktop_config.json):

{
  "mcpServers": {
    "harmony": {
      "command": "npx",
      "args": ["-y", "@codeconductorai/harmony-mcp"]
    }
  }
}

2. Restart your MCP client, then call the login tool. It returns a loginUrl — open it in your browser and complete the login.

3. Call confirm_login once you've finished logging in.

4. Call setup_workspace (providing language and buildTool) and then upload_workspace to index your project. You're now ready to use get_context_bundle.

Tools

login

Starts a secure authentication session. Returns a loginUrl to open in your browser and a userCode.

confirm_login

Verifies and completes the authentication process after browser login.

• timeout (optional): Max seconds to wait for login (default: 300).

setup_workspace

Registers your current project as a workspace on the backend.

• language (required): Codebase language (e.g., JAVA, JAVASCRIPT, TYPESCRIPT, PYTHON).
• buildTool (required): Build tool used (e.g., MAVEN, GRADLE, NPM).

upload_workspace

Zips the current working directory (excluding common folders like node_modules and .git) and indexes it on the cloud. Automatically runs setup_workspace if not already initialized.

get_context_bundle

Retrieves a ranked XML context bundle containing the most relevant code snippets from your indexed workspace based on your prompt.

• prompt (required): The natural-language question or instruction.

Local Development

npm install
npm start