EngineeringOS MCP
EngineeringOS MCP is an evidence-first MCP server for engineering investigations, gathering code, Git, log, test, and security evidence without inventing root causes.
Investigate engineering questions via
investigate, combining commits, diffs, code search, log search, and test results.Inspect Git history:
recent_changes(commits),git_diff(commit diff),analyze_change(changed files).Search code and logs:
search_code,search_logs.Plan and run tests:
test_plandetects runners;run_testsexecutes allow-listed suites in sandbox/disposable copy.Analyze dependencies and SBOMs:
software_inventory,cyclonedx_sbom,dependency_health.Index code and query symbols/call graphs:
index_code,find_symbol,dependency_graph,lsp_symbols.Export/ingest source-free code maps and query hosted maps:
export_code_map,ingest_code_map,map_find_symbol,map_dependency_graph,map_status.Run diagnostics and security scans:
diagnostics,code_security_scan,security_scan,vulnerability_scan.Assess repo overview, language profile, and production readiness:
repo_overview,language_profile,production_readiness.
Provides tools for gathering Git evidence from repositories — recent commits and subjects/refs, single-commit stat-and-patch diffs, and the files changed by a given revision — used as evidence for downstream impact analysis and root-cause reasoning.
Click on "Deploy Server".
Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state.
In the chat, type
@followed by the MCP server name and your instructions, e.g., "@EngineeringOS MCP investigate why the sample-repo tests are failing and gather evidence from git and logs"
That's it! The server will respond to your query, and you can continue using it as needed.
Here is a step-by-step guide with screenshots.
EngineeringOS MCP
Evidence-first engineering workflows for MCP clients. The server gathers code, Git, logs, and test evidence; it never invents a root-cause claim.
See ROADMAP.md for current state, what's deliberately deferred and why, and the suggested next increment. See VERDICT.md for an evidence-based assessment of whether this is actually a good product to solve developer problems, and why.
Quick install
To just use the CLI (not develop the project itself), install straight from GitHub — no PyPI account needed:
irm https://raw.githubusercontent.com/kl987456/engineeringos-mcp/master/install.ps1 | iexcurl -fsSL https://raw.githubusercontent.com/kl987456/engineeringos-mcp/master/install.sh | bashBoth scripts just run pip install against this repo — read install.ps1 or install.sh before piping them into your shell, same as you would for any installer. This gives you engineeringos-mcp, engineeringos-dashboard, engineeringos-eval, engineeringos-preflight, and engineeringos-map on PATH. Register it with Claude Code globally (works in every project, not just this repo):
claude mcp add engineeringos -s user -- engineeringos-mcpRelated MCP server: OpsLens AI MCP Server
Local run (for developing EngineeringOS itself)
Use a project-local virtual environment rather than installing into your system Python — this keeps EngineeringOS's dependencies isolated and, critically, avoids version conflicts with any operator-installed scanner CLI you later add (see the scanner setup note below).
python -m venv .venv
.venv\Scripts\pip install -e .
$env:PYTHONPATH = "."
.venv\Scripts\python -m engineeringos.serverAfter installing the package, use engineeringos-mcp for the local stdio server, engineeringos-dashboard for the local control room, engineeringos-eval sample-repo for the golden evidence regression, and engineeringos-preflight to validate production configuration without printing configured secret values.
See CLIENTS.md for ready-to-copy local setup for Claude Code, Codex, Cursor, and Gemini CLI, plus a two-agent investigator/verifier workflow.
Production HTTP run
Set ENGINEERINGOS_OIDC_ISSUER, ENGINEERINGOS_OIDC_AUDIENCE, ENGINEERINGOS_TENANT_ROOT, ENGINEERINGOS_INDEX_ROOT, ENGINEERINGOS_ALLOWED_HOSTS, and an operator-owned ENGINEERINGOS_TEST_WORKER; optionally set ENGINEERINGOS_OIDC_SCOPES, ENGINEERINGOS_OIDC_JWKS_URI, and ENGINEERINGOS_ALLOWED_ORIGINS. Then run uvicorn engineeringos.production:application --host 0.0.0.0 --port 8000. Use TLS and an allow-listed reverse proxy at the edge. Tenant repositories must be stored as one directory per validated token tenant claim, or remain in customer-side indexers or isolated workers. The production entrypoint refuses to start without a worker unless ENGINEERINGOS_REQUIRE_SANDBOX_WORKER=0 is explicitly set for local development.
The app emits conservative security headers; set ENGINEERINGOS_ENABLE_HSTS=1 only when HTTPS is guaranteed at the edge for the hostname and all subdomains.
Container deployment
docker-compose.yml runs as a non-root user with a read-only filesystem, dropped Linux capabilities, no-new-privileges, read-only tenant repositories, and a separate audit-log volume. Set ENGINEERINGOS_TENANT_REPOS before starting it. Set ENGINEERINGOS_AUDIT_LOG to enable JSONL audit events. ENGINEERINGOS_RATE_LIMIT_PER_MINUTE configures the per-tenant/per-subject tool-call guardrail (default: 120), while ENGINEERINGOS_RATE_LIMIT_KEYS bounds in-process limiter memory (default: 10,000). Multi-replica deployments should enforce a matching shared limit at the gateway.
Verification
Run the sample suite from its repository directory:
Push-Location sample-repo
python -m pytest -q
Pop-LocationLocal dashboard
Start the local-only control room with python -m dashboard.server and open http://127.0.0.1:8765. Set ENGINEERINGOS_AUDIT_LOG to the MCP JSONL audit file. It visualizes health, calls, success rate, errors, stale indexes, tenant activity, tool volume, security/worker signals, and recent audit events; it refreshes every ten seconds and sends no data externally.
If the optional sem CLI is installed, set ENGINEERINGOS_SEM_BIN and pass an entity to analyze_change for entity-level impact analysis. The server falls back to Git evidence when sem is unavailable.
code_security_scan runs Semgrep (SAST) and Gitleaks (secret detection) against the target repository from a disposable copy, each independently optional. Gitleaks needs no configuration beyond being on PATH or set via ENGINEERINGOS_GITLEAKS_BIN. Semgrep additionally requires ENGINEERINGOS_SEMGREP_CONFIG — a local rules file path, or a registry ruleset such as p/security-audit — since it has no config that is both meaningful and network-free by default; the tool reports an honest fallback for either scanner that isn't configured rather than failing outright, and only hard-fails if neither is. vulnerability_scan runs OSV-Scanner against detected dependency manifests for known-vulnerability matches; unlike the other scanners here, this queries the public osv.dev database by default (documented in the tool output's source label), and ENGINEERINGOS_OSV_SCANNER_OFFLINE=1 switches to a pre-downloaded local database instead. Install all three as standalone tools — never into this project's own environment (see SECURITY.md for why).
The diagnostics tool detects only approved project-native checks (Python compile, Ruff, ESLint, TypeScript, Go vet, and Cargo check), runs them from a disposable copy, and never accepts arbitrary commands from an MCP caller. test_plan discovers supported test projects without executing repository code. run_tests uses a fixed command allow-list for pytest, npm/pnpm/Yarn, Go, Cargo, .NET, Maven, Gradle, Swift, sbt, Dart, Mix, RSpec, PHPUnit, and CTest; callers may select a detected runner but can never supply a command. Network-avoiding/offline flags are used where the underlying runner supports them.
After index_code, dependency_graph queries bounded direct callers or callees from the local SQLite symbol map. Python references are populated from its AST, while deterministic call edges are also extracted for supported non-Python languages; optional Tree-sitter and LSP adapters improve structural symbol fidelity.
Run the golden evidence regression locally with python -m engineeringos.evaluations sample-repo. It checks that the investigation workflow returns code, log, and test evidence while keeping claim unset and confidence UNKNOWN.
Clients can read engineeringos://capabilities to see which optional integrations are actually active in the current process. It reports semantic-impact, security-scanner, sandbox-worker, and parser-backend status so unavailable integrations are not mistaken for supported evidence.
Approval-required permission tiers are enforced from a trusted token claim, defaulting to engineeringos_approvals. The claim must contain the exact approved tool names; change its name with ENGINEERINGOS_APPROVAL_CLAIM when integrating an authorization service.
lsp_symbols is an optional structural adapter seam. Set ENGINEERINGOS_LSP_ADAPTER to an operator-owned executable that accepts {repo_path, file_path, language, timeout_seconds} JSON on stdin and returns {"symbols": [{"name", "kind", "line", "end_line"}]}. The MCP never accepts the adapter command from a caller.
When no adapter is configured, lsp_symbols falls back to a default backend for Python only (install the lsp extra: python -m pip install -e ".[lsp]"), backed by multilspy. This default does not run on Windows — a live test hung for several minutes even with a 30-second timeout, while the identical scenario on Linux completed correctly in under 2 seconds — set ENGINEERINGOS_LSP_DEFAULT_FORCE_WINDOWS=1 to try it there anyway. Other languages multilspy supports (Rust, Java, Kotlin, Go, JS/TS, Ruby, C#, Dart) are not yet enabled by default; each needs external language-server availability verified before it can be trusted as a silent default. engineeringos://capabilities reports structural_symbol_default per language so this is never mistaken for broader support than it has.
For stronger structural indexing, install the optional parser set with python -m pip install -e ".[parsing]". The indexer records which backend it used in its evidence (python-ast, tree-sitter, tree-sitter (language-pack), or regex-fallback). If a grammar is unavailable, it safely falls back to Python AST or language-aware regex extraction rather than failing the repository scan. Indexing recognizes Python, JavaScript/JSX, TypeScript/TSX, Go, Rust, Java, Kotlin, Ruby, PHP, C, C++, C#, Swift, Scala, Lua, shell, Dart, and Elixir; parsing covers the 12 hand-tuned languages with native symbol-kind mappings (all but Kotlin, Lua, shell, and Dart).
Install the additional python -m pip install -e ".[parsing-pack]" extra to enable real structural parsing for Kotlin, Lua, shell, and Dart too, backed by tree-sitter-language-pack. This backend never fetches a grammar over the network from inside a tool call — it only uses one already cached locally — so it needs a one-time, explicit prefetch before it activates for a given language:
.venv\Scripts\python -c "import tree_sitter_language_pack as t; t.prefetch(['kotlin', 'lua', 'bash', 'dart'])"Elixir intentionally stays on the regex fallback: its grammar has no distinct node types for a function definition versus an ordinary call, so a naive mapping would misreport call sites as definitions.
Use language_profile before deeper analysis on a mixed repository. It reports source and test counts, indexed bytes, the actual parser backend selected for each detected language, and recognized build/dependency manifests without running project code.
Indexing limits individual source files to 2 MB and defaults to 100,000 source files per repository. Set ENGINEERINGOS_MAX_INDEX_FILES to a deliberate higher or lower bound. Deleted files are removed from the SQLite symbol and edge map during the next index pass.
For read-only tenant mounts, ENGINEERINGOS_INDEX_ROOT stores each repository map in a path-keyed directory outside the checkout. The production entrypoint requires this setting.
Source-free hosted code maps
Run index_code, then use export_code_map or engineeringos-map export <repo> <map.json> inside the customer's environment. Export fails when the local index is stale. The v1 map contains only normalized relative paths, language labels, SHA-256 file hashes, symbol locations, and call/reference edges—never raw source text. ingest_code_map validates the complete strict schema and fingerprint before transactionally replacing a tenant/project map; map_find_symbol and map_dependency_graph query that hosted metadata without a checkout. map_status compares the hosted fingerprint with a local export so synchronization drift is explicit. Map storage uses ENGINEERINGOS_MAP_ROOT, falling back to the required external ENGINEERINGOS_INDEX_ROOT, and is partitioned by authenticated tenant plus project ID.
Repository-wide evidence tools stop after 100,000 candidate files by default; set ENGINEERINGOS_MAX_SCAN_FILES deliberately when handling a larger repository. Production numeric limits are range-checked by both startup and engineeringos-preflight, and /readyz returns HTTP 503 if required runtime storage or sandbox-worker readiness is lost.
Available Tools
27 toolsanalyze_changeBRead-onlyIdempotent
List files changed by a Git revision as evidence for downstream impact reasoning.
Inputs: repo_path (required), entity, revision.
code_security_scanBRead-onlyIdempotent
Run operator-installed Semgrep (SAST) and Gitleaks (secret detection) against the target repository from a disposable copy; each is independently optional and reports an honest fallback when not configured.
Inputs: repo_path (required), timeout.
cyclonedx_sbomARead-onlyIdempotent
Generate a deterministic CycloneDX 1.6 component inventory from supported local manifests and lockfiles; performs no vulnerability enrichment.
Inputs: repo_path (required).
dependency_graphBRead-onlyIdempotent
Query indexed symbol-reference edges for direct callers or callees; evidence is limited to the local index.
Inputs: symbol (required), repo_path (required), direction, max_results.
dependency_healthBRead-onlyIdempotent
Inventory supported dependency manifests and lockfiles; does not make vulnerability claims.
Inputs: repo_path (required).
diagnosticsARead-onlyIdempotent
Run detected project-native diagnostics in a disposable copy; returns evidence only and never accepts arbitrary commands.
Inputs: repo_path (required), timeout.
export_code_mapBRead-onlyIdempotent
Export a strict source-free map of indexed paths, hashes, symbols, and graph edges; never includes raw source.
Inputs: repo_path (required).
find_symbolCRead-onlyIdempotent
Find indexed symbols across all supported languages by name.
Inputs: name (required), repo_path (required), max_results.
git_diffARead-onlyIdempotent
Show the stat-and-patch diff for a single Git commit, as evidence for a specific change.
Inputs: repo_path (required), commit.
index_codeBRead-onlyIdempotent
Build or update the local symbol map for a repository. Raw source is not stored in the index.
Inputs: repo_path (required).
ingest_code_mapC
Validate and transactionally store a source-free code map for one tenant project.
Inputs: code_map (required), project_id (required).
investigateBRead-onlyIdempotent
Gathers evidence (recent commits + diffs, code search, log search, test results) relevant to an engineering question. Returns evidence only — it does not claim a root cause; reason over the returned evidence yourself.
Inputs: question (required), repo_path (required), since, log_path, +2 more.
language_profileBRead-onlyIdempotent
Inventory languages, test files, parser backends, source size, and build ecosystems in a polyglot repository.
Inputs: repo_path (required).
lsp_symbolsCRead-onlyIdempotent
Use the operator-configured structural symbol adapter for one repository file; returns bounded symbol evidence only.
Inputs: file_path (required), repo_path (required), timeout, language.
map_dependency_graphCRead-onlyIdempotent
Query callers or callees from a hosted source-free code map.
Inputs: symbol (required), project_id (required), direction, max_results.
map_find_symbolCRead-onlyIdempotent
Find symbols in a hosted source-free code map without accessing a customer checkout.
Inputs: name (required), project_id (required), max_results.
map_statusBRead-onlyIdempotent
Report hosted source-free map counts and compare an optional local source fingerprint for staleness.
Inputs: project_id (required), source_fingerprint.
production_readinessBRead-onlyIdempotent
Gather deterministic evidence for production readiness; makes no release decision.
Inputs: repo_path (required).
recent_changesCRead-onlyIdempotent
Commits touching a repo (or one file) within a time window, with subjects and refs.
Inputs: repo_path (required), since, file_path.
repo_overviewBRead-onlyIdempotent
Gather a fast evidence-only inventory of repository shape, languages, tests, index freshness, and deployment artifacts.
Inputs: repo_path (required).
run_testsCRead-onlyIdempotent
Runs detected project-native test suites in a sandbox worker or disposable local copy and reports bounded evidence.
Inputs: repo_path (required), scope, runner, timeout.
search_codeBRead-onlyIdempotent
Bounded text search across supported source and configuration files; returns file-and-line evidence.
Inputs: query (required), repo_path (required), max_results.
search_logsCRead-onlyIdempotent
Searches a log file for lines matching a query.
Inputs: query (required), log_path (required), max_results.
security_scanCRead-onlyIdempotent
Run the operator-configured MCP security scanner and return findings as evidence.
Inputs: server_path (required).
software_inventoryARead-onlyIdempotent
Extract bounded cross-language dependency coordinates and Package URLs from local manifests and lockfiles without network access.
Inputs: repo_path (required).
test_planARead-onlyIdempotent
Detect allow-listed test runners and report whether each required toolchain is locally available without executing project code.
Inputs: repo_path (required).
vulnerability_scanARead-onlyIdempotent
Run the operator-installed OSV-Scanner against detected dependency manifests for known-vulnerability matches. By default this queries the public osv.dev database over the network; set ENGINEERINGOS_OSV_SCANNER_OFFLINE=1 to use a pre-downloaded local database instead.
Inputs: repo_path (required), timeout.
Tool Schema Changelog
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
Loading tool schema changelog…
TDQS
Scored across 27 tools
Several tools have overlapping purposes and could be confused: repo_overview vs language_profile vs dependency_health vs software_inventory all gather similar inventory evidence; find_symbol vs map_find_symbol and dependency_graph vs map_dependency_graph are nearly identical except for local vs hosted scope; security_scan vs code_security_scan overlap in security scanning. Descriptions help somewhat, but boundaries are fuzzy.
Mostly snake_case verb_noun style (e.g. index_code, search_code, run_tests), but there are notable deviations: 'investigate' and 'diagnostics' are noun-only, 'production_readiness' is a noun phrase, and 'cyclonedx_sbom' is a product name. The map_ prefixed tools add a second naming dimension.
27 tools is heavy for a code analysis server, and several pairs are near-duplicates (map_ vs local variants), suggesting over-fragmentation rather than distinct value. It pushes into the 25+ range that typically signals excessive surface area.
The surface covers a wide lifecycle: indexing, symbol search, dependency analysis, testing, security, SBOM, and map ingestion/export. Minor gaps exist (e.g. no explicit tool for retrieving a full security report or package license compliance), but most core workflows are covered.
Related MCP Connectors
Read-only release evidence for coding agents: findings, deliveries, source and runtime data.
Tenant-scoped evidence intake and controlled AI context over MCP.
Discover software problems, analyze evidence, and create implementation-ready Build plans.
Hosted MCP server for pre-action AI governance verdicts, model routing, and evidence verification.
Related MCP Servers
- AlicenseNot gradedqualityDmaintenanceStandalone MCP harness for cross-system process evidence, code-change impact review, and natural-language repository checkout mapping, with optional accelerators like CodeGraph.1MIT
- FlicenseNot gradedqualityDmaintenanceProvides MCP tools to search engineering runbooks and historical incidents using semantic retrieval, supporting evidence-grounded incident investigation.-
- FlicenseNot gradedqualityDmaintenanceAn MCP-native AI incident response system that empowers agents to investigate production incidents, collect evidence, hypothesize root causes, and drive controlled remediation and recovery verification.1-

Celmis MCP Serverofficial
AlicenseNot gradedqualityBmaintenanceEnables querying indexed code across multiple repositories with file-level citations, reviewing pull requests, auditing dependencies, and exporting SBOMs and evidence packs through MCP tools.3AGPL 3.0