embark-cli 1.1.7

package/INTEGRATION_TESTING.md

@@ -0,0 +1,243 @@
+# Integration Testing with Claude Code
+
+This guide explains how to test the Embark MCP Server integration with Claude Code and verify that roots are being passed correctly.
+
+## Quick Start
+
+### 1. Configure Claude Code
+
+Add your development server to `.mcp.json` in your project root or Claude Code's global config:
+
+```json
+{
+  "mcpServers": {
+    "embark-mcp": {
+      "command": "node",
+      "args": ["/Users/dmitry.loktev/Projects/embark-remote-mcp/dist/index.js"],
+      "env": {
+        "REPOSITORY_GIT_REMOTE_URL": "https://github.com/jetbrains/embark-mcp.git",
+        "ENABLE_LOCAL_LOGS": "true"
+      }
+    }
+  }
+}
+```
+
+**Important**: Set `ENABLE_LOCAL_LOGS=true` to enable detailed logging.
+
+### 2. Build the Server
+
+```bash
+npm run build
+```
+
+### 3. Start Log Watching
+
+In a terminal, run the log watcher script:
+
+```bash
+./watch-logs.sh
+```
+
+This will:
+- Monitor `~/.embark/debug.log` in real-time
+- Highlight roots-related log entries in green
+- Show errors in red and warnings in yellow
+- Wait for the log file if it doesn't exist yet
+
+### 4. Restart Claude Code
+
+Restart Claude Code to load the MCP server with the new configuration.
+
+### 5. Watch for Logs
+
+When Claude Code connects to your MCP server, you should see log entries like:
+
+```json
+{
+  "timestamp": "2025-10-15T09:49:23.456Z",
+  "level": "info",
+  "message": "Server launch initiated."
+}
+{
+  "timestamp": "2025-10-15T09:49:23.500Z",
+  "level": "info",
+  "message": "ListRoots request received"
+}
+{
+  "timestamp": "2025-10-15T09:49:23.501Z",
+  "level": "info",
+  "message": "ListRoots returning repository root",
+  "data": {
+    "uri": "embark://https://github.com/jetbrains/embark-mcp.git",
+    "name": "embark-mcp"
+  }
+}
+```
+
+## What to Look For
+
+### ✅ Successful Integration
+
+You should see these log entries when Claude Code connects:
+
+1. **Server startup**: "Server launch initiated"
+2. **Initialization**: "Server connected to stdio transport"
+3. **Roots request**: "ListRoots request received"
+4. **Roots response**: "ListRoots returning repository root" with URI and name
+
+### ❌ Common Issues
+
+**No logs appearing:**
+- Check `ENABLE_LOCAL_LOGS=true` is set in your `.mcp.json`
+- Verify the server path in `.mcp.json` points to `dist/index.js`
+- Restart Claude Code
+
+**"No REPOSITORY_GIT_REMOTE_URL configured" warning:**
+- Add `REPOSITORY_GIT_REMOTE_URL` to the `env` section in `.mcp.json`
+- Restart Claude Code
+
+**Server not starting:**
+- Check the build succeeded: `ls dist/index.js`
+- Look for TypeScript errors: `npm run build`
+- Verify Node.js version: `node --version` (should be 18+)
+
+## Advanced: Manual Log Inspection
+
+If you prefer to inspect logs manually:
+
+```bash
+# View entire log file
+cat ~/.embark/debug.log
+
+# View recent entries
+tail -n 50 ~/.embark/debug.log
+
+# Follow logs in real-time
+tail -f ~/.embark/debug.log
+
+# Search for roots-related entries
+grep -i "root" ~/.embark/debug.log
+
+# Filter by level
+jq 'select(.level == "error")' ~/.embark/debug.log
+```
+
+## Log File Location
+
+Logs are written to: `~/.embark/debug.log`
+
+The log file uses JSON format with entries like:
+
+```json
+{
+  "timestamp": "2025-10-15T09:49:23.456Z",
+  "level": "info",
+  "message": "...",
+  "data": { ... }
+}
+```
+
+## Testing Workflow
+
+1. **Start log watcher** in one terminal:
+   ```bash
+   ./watch-logs.sh
+   ```
+
+2. **Make code changes** in your editor
+
+3. **Rebuild**:
+   ```bash
+   npm run build
+   ```
+
+4. **Restart Claude Code** to reload the server
+
+5. **Watch logs** for the roots/list request and response
+
+6. **Test functionality** by asking Claude to search code or interact with your repository
+
+## Verifying Roots Are Passed
+
+To verify Claude Code is receiving and using the roots:
+
+1. Check logs show "ListRoots returning repository root"
+2. The root URI should match your `REPOSITORY_GIT_REMOTE_URL`
+3. The root name should be extracted from the repository URL
+4. Ask Claude to search your codebase - it should be aware of the repository context
+
+## Example Log Session
+
+Here's what a successful session looks like:
+
+```
+============================================================
+Embark MCP Server Log Watcher
+============================================================
+
+Log file: /Users/dmitry.loktev/.embark/debug.log
+
+✓ Watching logs...
+ℹ Press Ctrl+C to stop
+
+------------------------------------------------------------
+
+{
+  "timestamp": "2025-10-15T09:49:23.456Z",
+  "level": "info",
+  "message": "Server launch initiated."
+}
+{
+  "timestamp": "2025-10-15T09:49:23.500Z",
+  "level": "info",
+  "message": "ListRoots request received"
+}
+{
+  "timestamp": "2025-10-15T09:49:23.501Z",
+  "level": "info",
+  "message": "ListRoots returning repository root",
+  "data": {
+    "uri": "embark://https://github.com/jetbrains/embark-mcp.git",
+    "name": "embark-mcp"
+  }
+}
+```
+
+## Troubleshooting
+
+### Logs show old timestamps
+
+The log file persists across sessions. Look for the most recent "--- New Session: ..." marker:
+
+```bash
+grep "New Session" ~/.embark/debug.log
+```
+
+### Want to clear logs
+
+```bash
+rm ~/.embark/debug.log
+```
+
+Then restart Claude Code to create a fresh log.
+
+### Server crashes immediately
+
+Check stderr output in Claude Code's console or add stderr logging to see the error.
+
+## Integration with Automated Tests
+
+You can also run the automated test script while watching logs:
+
+**Terminal 1:**
+```bash
+./watch-logs.sh
+```
+
+**Terminal 2:**
+```bash
+ENABLE_LOCAL_LOGS=true node test-roots.mjs
+```
+
+This lets you see both the test output and the detailed server logs side-by-side.

package/MULTI_REPOSITORY_SEARCH.md

@@ -0,0 +1,242 @@
+# Multi-Repository Search
+
+The Embark MCP server now supports searching across multiple Git repositories simultaneously, with flexible filtering options.
+
+## Overview
+
+When multiple workspace roots are provided by the MCP client, the server will:
+
+1. **Discover** all Git repositories from the provided roots
+2. **Add** repositories provided via environment variables (optional)
+3. **Exclude** repositories based on environment variables (optional)
+4. **Search** across all repositories in parallel
+5. **Aggregate** results with clear repository labels
+
+## How It Works
+
+### Default Behavior
+
+By default, when multiple repositories are discovered from workspace roots, the semantic code search will search **all of them** and return aggregated results.
+
+```bash
+# No configuration needed - searches all discovered repositories
+node dist/index.js
+```
+
+### Adding and Filtering Repositories
+
+You can control which repositories are searched using environment variables:
+
+#### Include Additional Repositories
+
+Use `INCLUDE_REPOSITORY_URLS` to **add** repositories to the search list, even if they are not part of the current workspace roots (for example, a remote microservice you haven't cloned locally).
+
+```bash
+export INCLUDE_REPOSITORY_URLS="https://github.com/owner/repo1.git,https://github.com/owner/repo2.git"
+node dist/index.js
+```
+
+All discovered repositories **plus** the ones in `INCLUDE_REPOSITORY_URLS` will be searched.
+
+#### Exclude Specific Repositories
+
+Use `EXCLUDE_REPOSITORY_URLS` to skip certain repositories:
+
+```bash
+export EXCLUDE_REPOSITORY_URLS="https://github.com/owner/large-repo.git,https://github.com/owner/deprecated-repo.git"
+node dist/index.js
+```
+
+All discovered (and included) repositories **except** those listed in `EXCLUDE_REPOSITORY_URLS` will be searched.
+
+#### Combine Both Filters
+
+You can add repositories and then remove specific ones with the exclude list:
+
+```bash
+export INCLUDE_REPOSITORY_URLS="https://github.com/owner/repo1.git,https://github.com/owner/repo2.git,https://github.com/owner/repo3.git"
+export EXCLUDE_REPOSITORY_URLS="https://github.com/owner/repo3.git"
+node dist/index.js
+```
+
+This will search all discovered repositories, plus `repo1` and `repo2`, while skipping `repo3`.
+
+## Environment Variables
+
+### `INCLUDE_REPOSITORY_URLS`
+
+- **Format**: Comma-separated list of Git repository URLs
+- **Effect**: Repositories in this list will be added to the discovered set and searched alongside any workspace repositories
+- **Example**: `"https://github.com/org/repo1.git,git@github.com:org/repo2.git"`
+
+### `EXCLUDE_REPOSITORY_URLS`
+
+- **Format**: Comma-separated list of Git repository URLs
+- **Effect**: Repositories in this list will be skipped
+- **Example**: `"https://github.com/org/large-repo.git"`
+
+### Repository URL Matching
+
+Repository URLs are matched by exact string when deduping or excluding:
+
+- When **including** a repository, you can provide any valid Git URL (it doesn't need to be part of the current workspace).
+- When **excluding** or when you want to target a discovered repository explicitly, use the exact remote URL shown in server logs.
+
+Common formats:
+- HTTPS: `https://github.com/owner/repo.git`
+- SSH: `git@github.com:owner/repo.git`
+- Enterprise: `https://git.company.com/owner/repo.git`
+
+## Search Behavior
+
+### Single Repository
+
+When only one repository is available (after filtering or discovery), the search behaves like a traditional single-repository search with clean, simple output.
+
+### Multiple Repositories
+
+When multiple repositories are available, the search:
+
+1. Queries all repositories **in parallel** for better performance
+2. Aggregates results by repository
+3. Returns formatted results with repository headers:
+
+```
+Searched 3 of 3 repositories for "authentication handler". Found 15 total results.
+
+## Repository: frontend-app
+
+Found 5 results for "authentication handler" in repository "https://github.com/owner/frontend-app.git":
+
+1. File=src/auth/handler.ts, offset=120:450, similarity=0.892, type=FUNCTION
+   ...
+
+---
+
+## Repository: backend-api
+
+Found 10 results for "authentication handler" in repository "https://github.com/owner/backend-api.git":
+
+1. File=api/auth.py, offset=200:550, similarity=0.876, type=CLASS
+   ...
+```
+
+## Backward Compatibility
+
+This feature is fully backward compatible:
+
+- ✅ Single-repository setups continue to work unchanged
+- ✅ `REPOSITORY_GIT_REMOTE_URL` environment variable still supported as fallback
+- ✅ No changes to tool parameters or API
+- ✅ Existing integrations remain functional
+
+## Use Cases
+
+### Monorepo with Multiple Projects
+
+Search across all projects in a monorepo:
+
+```bash
+# Search all projects
+node dist/index.js
+```
+
+### Multi-Repo Development
+
+Search across related repositories you're working on:
+
+```bash
+# Add active development repos (even if they aren't part of the current workspace)
+export INCLUDE_REPOSITORY_URLS="https://github.com/org/frontend.git,https://github.com/org/backend.git"
+node dist/index.js
+```
+
+### Exclude Large/Archived Repositories
+
+Skip repositories that are large or not relevant:
+
+```bash
+# Exclude archived and large repos
+export EXCLUDE_REPOSITORY_URLS="https://github.com/org/archived-legacy.git,https://github.com/org/huge-data-repo.git"
+node dist/index.js
+```
+
+## Troubleshooting
+
+### No Results Across All Repositories
+
+If you're getting "No repositories available for search":
+
+1. Check that Git repositories are present in your workspace roots
+2. Verify repositories have a `git remote` configured
+3. If using `INCLUDE_REPOSITORY_URLS`, ensure the URLs are valid Git remotes (you can use this even when no workspace roots are available)
+4. If using `EXCLUDE_REPOSITORY_URLS`, double-check that you're not excluding every repository
+5. Check server logs for discovered and included repository URLs
+
+### Repository Not Being Searched
+
+If a repository isn't appearing in results:
+
+1. Verify it was discovered during initialization (check logs)
+2. If using `INCLUDE_REPOSITORY_URLS`, ensure the URL is listed and matches the remote you expect
+3. If using `EXCLUDE_REPOSITORY_URLS`, ensure the URL is not listed (and that you are not excluding it indirectly with a duplicate format)
+4. Verify the repository URL format matches exactly (HTTPS vs SSH) to avoid duplicates being treated as different URLs
+
+### Performance with Many Repositories
+
+Searches across multiple repositories run in parallel, but:
+
+- Avoid adding unnecessary repositories via `INCLUDE_REPOSITORY_URLS` when troubleshooting performance
+- Use `pathFilter` parameter to narrow search within repositories
+- Large repositories may take longer to search
+
+## Implementation Details
+
+### Repository Discovery
+
+1. Server requests roots from MCP client using `listRoots()`
+2. Each root is checked for Git repositories using `git rev-parse --git-dir`
+3. Git remote URL is extracted using `git remote get-url origin`
+4. Repositories defined in `INCLUDE_REPOSITORY_URLS` are added (deduped by URL)
+5. Repositories are cached for the duration of the server session
+
+### Filtering Logic
+
+```
+All Discovered Repositories
+    ↓
+If INCLUDE_REPOSITORY_URLS is set:
+    Add repositories from include list (deduped by URL)
+    ↓
+If EXCLUDE_REPOSITORY_URLS is set:
+    Remove repositories in exclude list
+    ↓
+Filtered Repositories
+```
+
+### Search Execution
+
+- **Single repo**: Direct search, clean output
+- **Multiple repos**: Parallel searches, aggregated results
+- **No repos**: Clear error message
+
+## Future Enhancements
+
+Potential future improvements:
+
+- [ ] Support for repository name patterns (wildcards)
+- [ ] Per-repository search configuration
+- [ ] Result ranking across repositories
+- [ ] Repository-specific pathFilter
+- [ ] Dynamic repository discovery during runtime
+
+## Testing
+
+Run the test suite to see examples:
+
+```bash
+# Run multi-repository filter demonstration
+node test-multi-repo-filters.mjs
+```
+
+This will show example scenarios and configuration patterns.