Embark MCP Server

A Model Context Protocol (MCP) server that provides a proxy interface to Embark's semantic code search capabilities. This server enables LLM applications to search through code repositories using Embark's powerful indexing and similarity search.

Features

• Semantic Code Search: Search for code using natural language queries through Embark's semantic search engine
• MCP Protocol Compliance: Fully compatible with the Model Context Protocol standard
• JetBrains Account Authentication: Secure authentication with Embark's API using JetBrains Account OAuth
• Configurable Repositories: Search across different code repositories
• Fallback JWT Support: Supports GRAZIE_JWT_TOKEN for non-interactive environments

Installation

1. Clone the repository:

git clone <repository-url>
cd embark-mcp

2. Install dependencies:

npm install

3. Build the project:

npm run build

Configuration

Authentication

This server uses JetBrains Account OAuth for authentication by default.

First-Time Authorization

The OAuth flow is triggered when you first use a search tool. To manually trigger the authorization before using it with Claude Desktop:

1. Start the server: npx embark-mcp
2. In another terminal, trigger a search to start the OAuth flow:

   echo '{"method": "tools/call", "params": {"name": "embark_search", "arguments": {"text": "test"}}}' | npx embark-mcp

3. The server will automatically open a browser window to https://account.jetbrains.com
4. Log in with your JetBrains Account credentials
5. Review and accept the authorization request for Embark access
6. The browser will redirect to a success page showing "Authorization successful, return to the terminal"
7. Return to your terminal - the server should now be authenticated

The authorization tokens are securely saved in ~/.jbaccount for future sessions, so you only need to do this once.

Environment Variables

• GRAZIE_JWT_TOKEN (optional): JWT authentication token for Embark API. If provided, it will be used instead of the OAuth flow. This is useful for non-interactive environments.
• JETBRAINS_AI_URL (optional): Base URL for JetBrains AI API (defaults to https://api.jetbrains.ai, can be set to https://api.stgn.jetbrains.ai/ for staging).
• REPOSITORY_ID (optional): Default repository ID to search in (can be overridden per search request)

Setting up Fallback Authentication (Optional)

If you need to use the server in a non-interactive environment, you can use a JWT token.

1. Obtain a JWT token from your Embark service administrator
2. Set the token as an environment variable:

export GRAZIE_JWT_TOKEN="your-jwt-token-here"
export REPOSITORY_ID="ultimate"  # optional default repository

Usage

Running the Server

Using npx (Recommended)

You can run the server directly using npx without cloning the repository:

# Optional: set a default repository
export REPOSITORY_ID="ultimate"

# Run the server and follow the on-screen instructions for OAuth login
npx embark-mcp

If you are using fallback JWT authentication:

# Set your authentication token
export GRAZIE_JWT_TOKEN="your-jwt-token-here"
export REPOSITORY_ID="ultimate"  # optional

# Run the server
npx embark-mcp

Running from Source

Start the MCP server:

npm start

Or for development with auto-reload:

npm run dev

Integrating with Claude Desktop

Add the server to your Claude Desktop configuration file:

macOS/Linux: ~/.config/claude/claude_desktop_config.json Windows: %APPDATA%/Claude/claude_desktop_config.json

Using npx (Recommended)

{
  "mcpServers": {
    "embark-mcp": {
      "command": "npx",
      "args": ["embark-mcp"],
      "env": {
        "JETBRAINS_AI_URL": "https://api.jetbrains.ai",
        "REPOSITORY_ID": "ultimate"
      }
    }
  }
}

Note: For the OAuth flow to work with Claude Desktop, you must complete the initial authorization process first. Follow the steps in the "First-Time Authorization" section above to trigger the OAuth flow and save the tokens before Claude Desktop attempts to use the server.

Using Local Installation

{
  "mcpServers": {
    "embark-mcp": {
      "command": "node",
      "args": ["/path/to/embark-mcp/dist/index.js"],
      "env": {
        "REPOSITORY_ID": "ultimate"
      }
    }
  }
}

Available Tools

embark_search

Search for code using Embark's semantic search engine.

Parameters:

• text (required): The text/code to search for
• repository (optional): The repository to search in (defaults to REPOSITORY_ID environment variable)

Example:

Search for "authentication middleware" in the codebase

Response Format:

Found 5 results for "authentication middleware" in repository "ultimate":

1. File=src/middleware/auth.js, offset=120:340, similarity=0.892, type=FUNCTION
2. File=lib/security/middleware.ts, offset=45:180, similarity=0.834, type=CLASS
3. File=routes/auth.js, offset=890:1120, similarity=0.776, type=FUNCTION
...

API Reference

Embark API Integration

This server integrates with Embark's REST API:

• Endpoint: /user/v5/indexing/search
• Method: POST
• Authentication: Bearer token from JetBrains Account OAuth or GRAZIE_JWT_TOKEN via grazie-authenticate-jwt header
• Request Body:

  {
    "text": "search query",
    "repository": "repository-name"
  }

Response Structure

Embark returns search results with the following structure:

interface SearchResponse {
  searchResponse: {
    res: Array<{
      scoredText: {
        text: string;
        similarity: number;
      };
      sourcePosition: {
        relativePath: string;
        startOffset: number;
        endOffset: number;
      };
      indexItemType: string;
    }>;
  };
}

Development

Building

npm run build

Development Mode

npm run dev

Watch Mode

npm run watch

Troubleshooting

Common Issues

1. OAuth Error:
   • Ensure your browser is available to complete the login flow.
   • If behind a firewall, ensure that https://www.jetbrains.com and http://localhost:62345 (or a nearby port) are accessible.
   • If the browser doesn't open automatically, copy the URL from the terminal and open it manually.
2. Authentication Error (JWT): Ensure your GRAZIE_JWT_TOKEN is valid and not expired. This is only relevant if you are using fallback authentication.
3. Connection Error: Check that the JETBRAINS_AI_URL is correct and accessible.
4. No Results: Verify the repository name exists and is accessible with your token.

Error Messages

• Failed to get authorization code: The OAuth flow was not completed successfully.
• Embark API error (401): Invalid or expired token (either from OAuth or JWT).
• Embark API error (404): Repository not found or not accessible.

License

MIT

Contributing

1. Fork the repository
2. Create a feature branch
3. Make your changes
4. Submit a pull request

Support

For issues related to:

• This MCP server: Open an issue in this repository
• Embark API: Contact your Embark service administrator
• Model Context Protocol: See the official MCP documentation