MCP server proxy for Embark code search
npm install embark-mcpA 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.
- 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
1. Clone the repository:
``bash`
git clone
cd embark-mcp
2. Install dependencies:
`bash`
npm install
3. Build the project:
`bash`
npm run build
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:
bash`
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
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.
#### 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 add to searches. These repositories are searched in addition to any discovered from workspace roots. Useful when your working directory does not contain all repos you want to search. Example: "https://github.com/owner/repo1.git,https://github.com/owner/repo2.git"
- (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.
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:
`bash`
export GRAZIE_JWT_TOKEN="your-jwt-token-here"
export REPOSITORY_GIT_REMOTE_URL="https://github.com/owner/repo.git" # optional default repository
#### Using npx (Recommended)
You can run the server directly using npx without cloning the repository:
`bashOptional: set a default repository
export REPOSITORY_GIT_REMOTE_URL="https://github.com/owner/repo.git"
If you are using fallback JWT authentication:
bash
Set your authentication token
export GRAZIE_JWT_TOKEN="your-jwt-token-here"
export REPOSITORY_GIT_REMOTE_URL="https://github.com/owner/repo.git" # optionalRun the server
npx embark-mcp
`#### Running from Source
Start the MCP server:
bash
npm start
`Or for development with auto-reload:
bash
npm run dev
`$3
Add the server to your Claude Desktop configuration file:
macOS/Linux:
Windows: #### Using npx (Recommended)
json
{
"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
json
{
"mcpServers": {
"embark-mcp": {
"command": "node",
"args": ["/path/to/embark-mcp/dist/index.js"],
"env": {
"REPOSITORY_GIT_REMOTE_URL": "https://github.com/owner/repo.git"
}
}
}
}
`$3
####
Search for code using Embark's semantic search engine.
Parameters:
-
(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 for code that uses specific dependencies using Embark's semantic search.
Parameters:
-
(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 versionExample:
`
Search for code that uses React hooks with specific dependencies
Dependencies Parameter Example:
json
[
{"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
$3
This server integrates with Embark's REST API endpoints:
#### Semantic Code Search
- Endpoint:
(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:
`json
{
"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:
- Method: POST
- Authentication: Bearer token from JetBrains Account OAuth or via grazie-authenticate-jwt header
- Request Body:
`json
{
"index": "ProductionIndices.CodeBlocks",
"text": "search query",
"dependencies": [
{"dependency": "react", "version": "18.0.0"}
],
"maxResults": 10,
"minScore": 0.0,
"logAllowed": false,
"searchPipelineConfig": "SearchPipelineConfig.SearchOnly"
}
`$3
#### Semantic Code Search Response
Embark returns search results with the following structure:
typescript
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:
typescript
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
$3
bash
npm run build
`$3
bash
npm run dev
`$3
bash
npm run watch
`Troubleshooting
$3
1. OAuth Error:
- Ensure your browser is available to complete the login flow.
- If behind a firewall, ensure that
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.$3
-
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
Usage Analytics & Dashboard
The MCP server records structured JSON stats for each server initialization, Embark API call, and search invocation. Files are grouped per calendar day and stored under
~/.embark/stats/YYYY-MM-DD.json, making it easy to audit historical usage or inspect failure cases.$3
For a one-liner that starts the dashboard server and opens it in your default browser:
`bash
npx embark-mcp stats --port 43210
`If you prefer to start the server without opening a browser automatically, use:
bash
npx embark-mcp stats-server --port 43210
`The dashboard renders:
- Searches per day (semantic, dependency, multi-repo summaries)
- Estimated token usage per day
- Average response times
- Counts of error HTTP status codes
- A rolling feed of recent events for quick debugging
Data refreshes automatically every 15 seconds and never leaves your machine because everything is served directly from the local