Introducing a new way to review your PRs.

Read the announcement

semgrep / semgrep

Lightweight static analysis for many languages. Find bug variants with patterns that look like source code.

View on GitHub

13 documents · Updated Nov 16, 2026

docs / rpc-lsp-integrations

RPC, Legacy LSP, and MCP Integrations

Overview

This area contains three integration surfaces that expose Semgrep engine behavior outside the normal CLI scan path: the Python-to-OCaml RPC bridge in src/rpc/** and cli/…/rpc*.py, the legacy LSP server in src/lsp_legacy/**, and the MCP/agent hooks in cli/src/semgrep/mcp/**.

The OCaml RPC server starts at src/rpc/RPC.ml. Python callers in cli/…/rpc.py launch semgrep-core -rpc, serialize a semgrep_output_v1 FunctionCall as ATD JSON, prefix it with a byte-length header plus newline, write it to stdin, and read the same length-prefixed protocol from stdout. RPC.handle_request decodes the packet into Out.rpc_call, creates a tracing span from the optional parent span ID, dispatches through handle_call, wraps errors as RetError, attaches simple profiling results, and writes an Out.function_result. RPC.handle_multiple_requests can serve multiple sequential requests on one process, while cli/src/semgrep/rpc.py::rpc_call still uses a one-call subprocess and RpcSession keeps a long-lived process for back-to-back calls.

src/rpc/RPC_return.ml owns the OSS implementations behind RPC calls: applying text edits, formatting normal and SARIF output, collecting contributions, and validating rule files. src/rpc/RPC.ml also exposes feature gates for Pro-backed operations through mutable hooks declared in src/rpc/RPC_return.ml: scan, dependency resolution, rule partition dumping, transitive reachability filtering, subproject matching, and symbol analysis. If a hook is absent, handle_call returns an explicit proprietary-feature error. The Python facade in cli/…/rpc_call.py is intentionally thin: each function constructs the matching out.Call*, invokes rpc_call, checks the expected out.Ret*, and returns fallbacks only at the integration boundary.

The legacy language server starts at src/lsp_legacy/Legacy_language_server.ml, which runs Legacy_ls.start. src/lsp_legacy/Legacy_ls.ml declares LSP capabilities for incremental text sync, workspace folders and file operations, hover, code actions, and execute-command support, then creates a Legacy_rpc_server.t. src/lsp_legacy/server/Legacy_rpc_server.ml is the JSON-RPC/LSP event loop over stdin/stdout: it reads Jsonrpc.Packet.t, converts client requests and notifications through the OCaml LSP library, delegates to Legacy_request_handler or Legacy_notification_handler, and applies Legacy_lsp_.Reply values either immediately or asynchronously. src/lsp_legacy/server/Legacy_lsp_.ml centralizes response, notification, custom notification, progress, and error-packet helpers.

Legacy LSP state lives in src/lsp_legacy/server/Legacy_session.ml. The session tracks workspace folders, cached target lists, cached scan results by file, user settings, metrics, and a mutex-protected cache of rules, open documents, skipped fingerprints, deployment ID, and initialization status. Initialization in src/lsp_legacy/requests/Legacy_initialize_request.ml parses initializationOptions.scan, hover/pro settings, metrics, workspace roots, and IntelliJ detection, initializes preemptive Lwt workers, caches targets, and moves the server to Running. Rules are loaded from local configuration, registry refs, or Semgrep App deployment scan config, with SCA and Secrets products filtered out for the legacy LS path.

LSP request dispatch is in src/lsp_legacy/requests/Legacy_request_handler.ml. Standard requests include initialize, code actions, hover, execute command, shutdown, and debug echo. Unknown requests are routed to custom handlers for semgrep/search, semgrep/searchOngoing, semgrep/showAst, semgrep/loginStart, semgrep/loginStatus, and semgrep/loginFinish. Notifications in src/lsp_legacy/notifications/Legacy_notification_handler.ml trigger rule refresh on initialized and semgrep/refreshRules, scans on document open/save and semgrep/scanWorkspace, target-cache updates for workspace/file changes, diagnostic clearing on delete, logout state updates, and server stop on exit.

Scans for the legacy LSP flow are orchestrated by src/lsp_legacy/scan_helpers/Legacy_scan_helpers.ml. run_semgrep chooses cached rules and either cached session targets or explicit targets, selects the Pro intrafile runner when the user setting and login/pro hook are available, otherwise runs OSS Core_scan.scan, preprocesses output, filters ignored fingerprints and clean git lines through Legacy_processed_run.of_matches, records metrics, and returns matches plus scanned files. scan_workspace, scan_open_documents, and scan_file wrap this in LSP progress and textDocument/publishDiagnostics notifications generated by src/lsp_legacy/scan_helpers/Legacy_diagnostics.ml. Code actions in src/lsp_legacy/requests/Legacy_code_actions.ml use cached scan results to offer quick fixes and ignore actions; src/lsp_legacy/custom_commands/Legacy_autofix_cmd.ml records that a client-applied fix occurred, while src/lsp_legacy/custom_commands/Legacy_ignore_cmd.ml adds a fingerprint to local skipped state and rescans the file.

Custom LSP features are implemented as request handlers rather than protocol extensions in the transport layer. src/lsp_legacy/custom_requests/Legacy_search.ml implements a streaming search protocol: semgrep/search parses signed patterns, optional language/fix fields, include/exclude globs, derives search rules for relevant workspace analyzers, stores a Legacy_search_config.t, and returns the first file with matches; semgrep/searchOngoing advances through the remaining files one request at a time. src/lsp_legacy/custom_requests/Legacy_showast.ml parses a file and returns the generic AST as an OCaml value string. src/lsp_legacy/custom_requests/Legacy_login_start.ml, Legacy_login_status.ml, and Legacy_loginfinish.ml coordinate browser login URLs, token polling, token persistence, deployment info, and rule refresh after login.

The MCP server is defined in cli/…/server.py using FastMCP. server_lifespan creates a SemgrepContext via cli/src/semgrep/mcp/semgrep.py::mk_context, starts tracing, attaches deployment/OAuth metadata, and terminates any child process on shutdown. Registered tools include schema/language helpers, AppSec Platform findings lookup, local and remote scan tools, custom-rule scans, AST dumping, supply-chain scans, and whoami; deregister_tools removes tools according to disable env vars, hosted/local mode, and stdio transport constraints. Local scans validate absolute paths and keep reads inside the MCP workspace unless SEMGREP_MCP_ALLOW_SCAN_OUTSIDE_WORKSPACE=true; remote scans accept in-memory CodeFile payloads.

MCP scan execution has two backends. The CLI backend in cli/src/semgrep/mcp/server.py::semgrep_scan_cli writes requested code into a temp directory, builds semgrep scan --json --experimental --x-mcp arguments, runs the semgrep CLI through cli/src/semgrep/mcp/semgrep.py::run_semgrep_output, parses SemgrepScanResult, rewrites temp paths back to relative paths, optionally elicits true/false-positive decisions, and attaches metrics. The RPC backend starts a local Pro daemon with semgrep mcp --experimental --pro --session-id ... in cli/src/semgrep/mcp/semgrep.py::mk_context when Pro is installed, a token is available, and USE_SEMGREP_RPC or local defaults permit it. cli/src/semgrep/mcp/semgrep_context.py::send_request writes newline-delimited JSON such as {"method":"scanFiles","files":...,"git_info":...} to that process and reads a single-line response; run_semgrep_via_rpc double-decodes the response and validates it as SemgrepScanResult.

The MCP hook entry points in cli/src/semgrep/mcp/hooks/** expose scans to AI-agent lifecycle hooks rather than MCP tool calls. hooks/post_tool.py scans files after Claude Code or Windsurf write operations and can block on findings. hooks/stop.py records Cursor edited files into a temp cache and scans them at a later stop hook, clearing the cache afterward. hooks/supply_chain.py detects package-install commands and runs a supply-chain scan that blocks when reachable findings are present. hooks/inject_secure_defaults.py injects security guidance into supported prompt flows. Shared hook settings in hooks/settings.py merge project and user .semgrep/plugin.json, currently for disabling supply-chain hooks.

Coupling

  • If adding or renaming an RPC call, update the ATD-generated function_call/function_return schema used by both src/rpc/RPC.ml and cli/…/rpc_call.py; the OCaml dispatcher and Python expected Ret* type must stay in lockstep or Python logs “incorrect kind of RPC response.”
  • If changing the RPC wire framing in src/rpc/RPC.ml, update cli/…/rpc.py at the same time. Both sides assume UTF-8 payloads framed as decimal byte length, newline, then payload; stdout must remain reserved for framed packets because Python treats nonnumeric stdout as a protocol error.
  • If changing Pro RPC behavior in src/rpc/RPC_return.ml, verify the hook registration path in the Pro build. src/rpc/RPC.ml returns proprietary-feature errors whenever hook_scan, dependency, reachability, subproject, or symbol-analysis refs are unset.
  • If adding an LSP execute command, add it to both src/lsp_legacy/requests/Legacy_execute_command.ml::supported_commands and the handler association list there; code actions in src/lsp_legacy/requests/Legacy_code_actions.ml can create commands that clients will not advertise unless capabilities include them.
  • If changing diagnostic ranges, severity mapping, or paths for LSP findings, check src/lsp_legacy/util/Legacy_convert_utils.ml, src/lsp_legacy/scan_helpers/Legacy_diagnostics.ml, and src/lsp_legacy/requests/Legacy_code_actions.ml together. Diagnostics, quick-fix lookup, hover/code-action ranges, and cached scan matches all compare LSP ranges derived from Semgrep CLI matches.
  • If changing legacy LSP initialization options, keep client JSON, src/lsp_legacy/requests/Legacy_initialize_request.ml, and src/lsp_legacy/server/Legacy_user_settings.ml aligned. The settings parser silently falls back to existing defaults when JSON decoding fails.
  • If changing semgrep/search parameters, update both src/lsp_legacy/custom_requests/Legacy_search.ml::Request_params.of_jsonrpc_params and mk_params; the parser is order-sensitive and tests/builders depend on the same field ordering.
  • If changing MCP scan result shape, update cli/src/semgrep/mcp/models.py::SemgrepScanResult, path-rewriting in cli/src/semgrep/mcp/server.py::remove_temp_dir_from_results, metrics in cli/src/semgrep/mcp/utilities/tracing.py::attach_scan_metrics, and the RPC daemon response consumed by cli/src/semgrep/mcp/semgrep.py::run_semgrep_via_rpc.
  • If changing MCP local file access, verify cli/src/semgrep/mcp/server.py::validate_local_files, resolve_within_workspace, cwd_workspace_dir, and hook callers in cli/…/stop.py. Tool and hook paths intentionally reject prompt-injected absolute paths outside the workspace unless the opt-in env var is set.
  • If changing MCP authentication, keep cli/…/utils.py, cli/…/token_verifier.py, cli/src/semgrep/mcp/server.py::setup_oauth_routes, and semgrep_findings in sync. Hosted OAuth uses JWT-derived deployment/user data, while local/API-token mode uses SEMGREP_APP_TOKEN roles and deployment lookup.

Risks

  • cli/…/rpc.py and src/rpc/RPC.ml are fragile around stdout discipline: any debug print to the OCaml RPC process stdout produces a nonnumeric header and makes Python report a protocol error instead of a typed RetError.
  • src/lsp_legacy/server/Legacy_rpc_server.ml intentionally processes replies with Lwt.dont_wait while continuing the event loop. If a new handler mutates non-mutex-protected session fields after entering a delayed reply, concurrent scans or notifications can observe stale or conflicting state; only Legacy_session.cached_session is protected by a mutex.
  • src/lsp_legacy/scan_helpers/Legacy_scan_helpers.ml::scan_file recalculates workspace targets when a file is not found but then tests membership against the pre-recalculation session_targets value. A newly created file may still be treated as an empty target set until another notification refreshes targets.
  • cli/…/semgrep_context.py uses newline-delimited JSON for the MCP daemon path, not the length-prefixed RPC protocol in src/rpc/RPC.ml/cli/…/rpc.py. Reusing one client against the other server will deadlock or parse garbage rather than fail with a shared protocol error.