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
• Multi-Repository Search: Search across multiple Git repositories simultaneously with filtering options
• Dependency-Based Search: Search for code that uses specific dependencies and libraries
• 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 with include/exclude filters
• 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": "semantic_code_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

Authentication

• 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 Configuration

• REPOSITORY_GIT_REMOTE_URL (optional): Default repository Git remote URL to search in (can be overridden per search request)
• REPOSITORY_ID (optional): Alternative way to specify default repository (fallback for REPOSITORY_GIT_REMOTE_URL)
• REPOSITORY_REVISION (optional): Default repository revision (commit hash, branch name, or tag) to search in. If not set, searches the latest indexed version.

Multi-Repository Filtering

• INCLUDE_REPOSITORY_URLS (optional): Comma-separated list of Git repository URLs to include in searches. When set, only these repositories will be searched. Example: "https://github.com/owner/repo1.git,https://github.com/owner/repo2.git"
• EXCLUDE_REPOSITORY_URLS (optional): Comma-separated list of Git repository URLs to exclude from searches. When set, these repositories will be skipped. Example: "https://github.com/owner/large-repo.git"

Other Options

• TYPE_TOKEN (optional): Endpoint type token, either USER (default) or APPLICATION. When set to APPLICATION, the server uses /application/* endpoints instead of /user/* endpoints.
• ENABLE_REMOTE_LOGS (optional): When set to true, includes logAllowed=true parameter in Embark API requests to enable remote logging for debugging purposes. Defaults to false.

Note: See MULTI_REPOSITORY_SEARCH.md for detailed documentation on multi-repository search and filtering.

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_GIT_REMOTE_URL="https://github.com/owner/repo.git"  # 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_GIT_REMOTE_URL="https://github.com/owner/repo.git"

# 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_GIT_REMOTE_URL="https://github.com/owner/repo.git"  # 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_GIT_REMOTE_URL": "https://github.com/owner/repo.git",
        "REPOSITORY_REVISION": "main",
        "TYPE_TOKEN": "USER",
        "ENABLE_LOCAL_LOGS": true,
        "ENABLE_REMOTE_LOGS": "false"
      }
    }
  }
}

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_GIT_REMOTE_URL": "https://github.com/owner/repo.git"
      }
    }
  }
}

Available Tools

semantic_code_search

Search for code using Embark's semantic search engine.

Parameters:

• text (required): The text/code to search for. Use detailed, descriptive natural language queries for best results. Examples: "function that validates user email addresses and returns boolean", "error handling middleware for HTTP requests with logging", "React component that renders a modal dialog with close button".
• pathFilter (optional): A specific directory or file to narrow the search. If not provided, the whole codebase is searched. Examples: "path/to/module", "path/to/module/submodule", "path/to/file/example.kt".
• repositoryGitRemoteUrl (optional): The repository Git remote URL to search in (defaults to REPOSITORY_GIT_REMOTE_URL environment variable)

Example:

{'text': 'Search for "authentication middleware" in the codebase', 'pathFilter': 'src'}

Response Format:

Found 10 results for "authentication middleware" in repository "https://github.com/owner/repo.git" (revision: "5e7f1ab4bf58e473e5d7f878eb2b499d7deabd29", pathFilter: "src")

1. File=src/middleware/auth.js, offset=120:340, similarity=0.892, type=FUNCTION
   Snippet:
   """
   export function authMiddleware(req, res, next) {
       const token = req.headers['authorization'];
       if (!token) return res.status(401).send('Missing token');
       try {
           req.user = verifyToken(token);
           next();
       } catch (err) {
           res.status(403).send('Invalid token');
       }
   }
   """
2. File=src/security/middleware.ts, offset=45:180, similarity=0.834, type=CLASS
   Snippet:
   """
   export class SecurityMiddleware {
       constructor(private readonly secret: string) {}
       handle(req: Request, res: Response, next: NextFunction) {
           if (!req.headers['x-api-key']) {
               res.status(401).json({ error: 'Unauthorized' });
           } else {
               next();
           }
       }
   }
   """
3. File=src/routes/auth.js, offset=890:1120, similarity=0.776, type=FUNCTION
   Snippet:
   """
   router.post('/login', async (req, res) => {
       const { username, password } = req.body;
       const token = await authenticate(username, password);
       res.json({ token });
   });
   """
...

search_in_dependencies

Search for code that uses specific dependencies using Embark's semantic search.

Parameters:

• text (required): The search query describing what to look for in relation to dependencies
• dependencies (required): Array of dependency objects with the following structure:
  • dependency (required): The dependency name
  • version (required): The dependency version

Example:

Search for code that uses React hooks with specific dependencies

Dependencies Parameter Example:

[
  {"dependency": "react", "version": "18.0.0"},
  {"dependency": "react-hooks", "version": "1.0.0"}
]

Response Format:

Found 3 results for "React hooks usage" with dependencies [react:18.0.0, react-hooks:1.0.0] in repository "https://github.com/owner/repo.git":

1. File=src/components/UserProfile.tsx, offset=45:180, similarity=0.891, type=FUNCTION
2. File=src/hooks/useAuth.ts, offset=12:95, similarity=0.834, type=FUNCTION
3. File=src/pages/Dashboard.tsx, offset=200:350, similarity=0.776, type=FUNCTION

Timings: search: 120ms, total: 150ms

API Reference

Embark API Integration

This server integrates with Embark's REST API endpoints:

Semantic Code Search

• Endpoint: /user/v5/indexing/search (or /application/v5/indexing/search when TYPE_TOKEN=APPLICATION)
• Method: POST
• Authentication: Bearer token from JetBrains Account OAuth or GRAZIE_JWT_TOKEN via grazie-authenticate-jwt header
• Request Body:

  {
    "text": "search query",
    "repository": "https://github.com/owner/repo.git",
    "revision": "main", // optional: commit hash, branch name, or tag
    "pathFilter": "dir" // optional: a file or a dir
  }

Dependencies Search

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

  {
    "index": "ProductionIndices.CodeBlocks",
    "text": "search query",
    "dependencies": [
      {"dependency": "react", "version": "18.0.0"}
    ],
    "maxResults": 10,
    "minScore": 0.0,
    "logAllowed": false,
    "searchPipelineConfig": "SearchPipelineConfig.SearchOnly"
  }

Response Structure

Semantic Code Search Response

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;
    }>;
  };
}

Dependencies Search Response

The dependencies search endpoint returns results with timing information:

interface DependenciesSearchResponse {
  results: Array<{
    searchResult: {
      sourcePosition: {
        relativePath: string;
        startOffset: number;
        endOffset: number;
      };
      indexItemType: string;
      similarity: number;
    };
    content: string;
  }>;
  timings: {
    [key: string]: number; // timing in milliseconds
  };
}

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