lancer

Lancer is a self-hosted MCP server written in .NET that indexes Git repositories and provides intelligent code search for AI agents using a hybrid search approach that combines BM25 full-text search, vector embeddings, and graph-based ranking. It focuses on a single MCP tool, Query, which orchestrates the indexing, symbol extraction, embedding generation (when an embedding service is available), and retrieval across configured repositories. To use Lancer, start the server after ensuring your PostgreSQL database and optional embedding service are available. Once running, you can query the codebase via the MCP tooling interface to locate symbols, navigate relationships, and retrieve contextual code snippets across indexed repositories. The server supports SSH and HTTPS Git URLs, incremental indexing, and per-repository configuration through the appsettings.json file.

Prerequisites:

• .NET 9.0 SDK installed on your host
• Docker and Docker Compose (for the database setup if you prefer a containerized PostgreSQL instance)
• Git installed and access to repositories you want to index

Step-by-step:

1. Clone the repository

git clone https://github.com/ItBurnsWhenICommit/lancer-mcp.git
cd lancer-mcp

2. Build the project (from the repository root):

dotnet build LancerMcp/LancerMcp.csproj

3. Prepare the database (examples show a PostgreSQL setup; adjust as needed):

• If using Docker:

# Example: start PostgreSQL using docker-compose if a compose file is provided
cd database
docker compose up -d

• Ensure the database is ready before starting the server (a test script may be provided in the repo, otherwise verify connectivity).

4. Configure repositories: Edit LancerMcp/appsettings.json to add your repositories, for example:

{
  "Repositories": [
    {
      "Name": "my-project",
      "RemoteUrl": "https://github.com/user/repo.git",
      "DefaultBranch": "main"
    }
  ]
}

5. Run the MCP server:

dotnet run --project LancerMcp/LancerMcp.csproj

6. Access the server:

• The MCP server will be available at http://localhost:5171 by default (adjust as needed in configuration). If embedding is configured and available, embeddings will be generated and used for semantic search; otherwise, only symbol search and navigation remain functional.

Tips and common considerations:

• Embedding service is optional. If unavailable, the server gracefully degrades to symbol search and navigation only.
• SSH support for repositories relies on LibGit2Sharp OpenSSH integration; ensure SSH keys are accessible if using SSH URLs.
• For large repos or multiple repos, monitor resource usage (CPU, memory) and adjust batch sizes and timeouts for embedding generation accordingly.
• If you run into port conflicts, verify that the service port (default 5171) is not in use and adjust configuration as needed.
• Ensure environment variables for database connectivity are correctly set (DB_HOST, DB_PORT, DB_NAME, DB_USER, DB_PASSWORD) and that the database is reachable from where the server runs.
• If you enable the embedding service, verify network access and model compatibility (CPU vs GPU environments).