Embark Remote 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
• JWT Authentication: Secure authentication with Embark's API using JWT tokens
• Configurable Repositories: Search across different code repositories

Installation

1. Clone the repository:

git clone <repository-url>
cd embark-remote-mcp

2. Install dependencies:

npm install

3. Build the project:

npm run build

Configuration

Environment Variables

• GRAZIE_JWT_TOKEN (required): JWT authentication token for Embark API
• EMBARK_BASE_URL (optional): Base URL for Embark API (defaults to https://api.app.stgn.grazie.aws.intellij.net)
• REPOSITORY_ID (optional): Default repository ID to search in (can be overridden per search request)

Setting up Authentication

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:

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

# Run the server
npx embark-remote-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-remote-mcp": {
      "command": "npx",
      "args": ["embark-remote-mcp"],
      "env": {
        "GRAZIE_JWT_TOKEN": "your-jwt-token-here",
        "REPOSITORY_ID": "ultimate"
      }
    }
  }
}

Using Local Installation

{
  "mcpServers": {
    "embark-remote-mcp": {
      "command": "node",
      "args": ["/path/to/embark-remote-mcp/dist/index.js"],
      "env": {
        "GRAZIE_JWT_TOKEN": "your-jwt-token-here",
        "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 or "ultimate")

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: 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. Authentication Error: Ensure your GRAZIE_JWT_TOKEN is valid and not expired
2. Connection Error: Check that the EMBARK_BASE_URL is correct and accessible
3. No Results: Verify the repository name exists and is accessible with your token

Error Messages

• GRAZIE_JWT_TOKEN environment variable is required: Set the JWT token environment variable
• Embark API error (401): Invalid or expired JWT token
• 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