Skip to main content
Glama

upload_local_coverage

Upload local coverage + current source and get back what's still untested — the core self-correction loop for writing tests without waiting on CI. Works for Python (pytest-cov) and TypeScript/JavaScript (vitest + Istanbul).

coverage_kind selects the dimension: "unit" (default) is the test-suite coverage flow described here; "browser" records an independent per-function browser-session dimension from a real browser run — any coverage format (Istanbul for a frontend harvest, pytest-cov for a coverage-instrumented backend serving the browser's requests), no junit. A branch's browser coverage is the union of what each producer last reached — its wrapped suite, and each recorded test's latest replay — and this upload replaces only the contribution of the producer it belongs to, per language (a TS-only browser upload never zeroes the Python dimension, and vice versa). It surfaces as browser_state (exercised/partial/unexercised) + browser_line_coverage_pct on each function and as the unexercised_browser gap in check_done, and never changes unit state.

Browser and manual uploads are also recorded in the branch's session ledger, so the Tests page can say what produced them. Pass session_id if you opened one; otherwise this upload becomes its own session, attributed to agent — you.

Run your tests with coverage locally first:

  • Python: pytest --cov --cov-branch --cov-context=test then coverage json --show-contexts -o coverage.json (pytest-cov's own --cov-report=json drops the per-test contexts)

  • TS/JS: vitest run --coverage --coverage.provider=istanbul --coverage.reporter=json → coverage/coverage-final.json

Pass a files map of {source_path: contents} for the files under test, plus exactly one of:

  • coverage_json — a single parsed report (pytest-cov or Istanbul).

  • coverage_reports — a list of parsed reports, merged with same-file-later-wins; use this to send both a pytest-cov and a vitest report in one upload for a mixed-language repo.

IMPORTANT: the keys of files must exactly match the file paths the coverage report records (relative to the directory the tests ran from). If they don't, nothing matches and functions_matched comes back 0.

Stored and returned paths are always repo-rooted. If your tests ran from a subdirectory of the repo (a monorepo package), pass path_prefix — the repo-root-relative directory the tests ran from (e.g. "backend"; "" if they ran at the repo root). Omit it and the server resolves the prefix against the repo tree best-effort, else stores paths as sent. All reports in one call share one root — split a multi-root upload into one call per root.

functions_matched and the untested/partial lists count whole functions only; React sub-units matched by the same upload are reported separately as units_matched, so those numbers stay comparable across uploads and against a repo's own sense of its size.

Uploads are merged per language, so a TS upload never wipes a branch's Python coverage (functions_preserved reports how many rows were kept). Upserts a single local analysis per branch, kept separate from any CI run. Returns the coverage summary plus the untested/partial functions and failing tests so you can fix them directly; the function ids work with get_function_detail and get_generated_prompt.

repository_id is the GitHub owner/repo (a repo UUID also works) — the same reference every other tool here takes.

Tool call template

Replace each placeholder with a value matching the input schema. Only required parameters are included; add optional parameters as needed.

{
  "id": 1,
  "jsonrpc": "2.0",
  "method": "tools/call",
  "params": {
    "arguments": {
      "repository_id": "<repository_id>",
      "branch": "<branch>",
      "files": "<files>"
    },
    "name": "upload_local_coverage"
  }
}

Input Schema

NameRequiredDescriptionDefault
filesYes
branchYes
junit_xmlNo
commit_shaNo
session_idNo
path_prefixNo
coverage_jsonNo
coverage_kindNounit
repository_idYes
coverage_reportsNo

Schema Changelog

Changes observed during successful MCP inspections.

  1. First observed

TDQS

A4.6/5.0
Behavior4/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

With no annotations, the description carries the full burden and mostly meets it: per-language merge/preservation semantics ('a TS upload never wipes a branch's Python coverage'), the replacement scope of browser uploads (union per producer), session-ledger recording and agent attribution, upsert identity, and the failure mode when file keys mismatch. It does not cover authorization, payload size limits, or error/retry behavior beyond the key-mismatch case.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness4/5

Is the description appropriately sized, front-loaded, and free of redundancy?

Purpose and the primary constraint are front-loaded, and the bulleted command/option blocks make the dense content scannable. It is nonetheless long and the browser-coverage paragraph is dense enough that key operational rules (exact-one-of, path matching) sit in the middle rather than being surfaced as hard constraints.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness5/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

For a 10-parameter mutation tool with no annotations and no output schema, the description is unusually complete: it names the returned fields (functions_matched, units_matched, functions_preserved, browser_state, browser_line_coverage_pct), the untested/partial and failing-test payload, and the follow-up tools the returned ids feed into.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters4/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema coverage is 0% across 10 parameters, so the description must compensate, and it does for most: files (keys must match report paths), coverage_json vs coverage_reports merge order (same-file-later-wins), coverage_kind values, path_prefix semantics with examples, repository_id format (owner/repo or UUID), and session_id behavior. However, commit_sha is never mentioned and junit_xml is only obliquely implied by 'no junit', leaving two parameters the agent must guess at.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

The first sentence gives a concrete verb and resource — 'Upload local coverage + current source and get back what's still untested' — plus the outcome. It distinguishes itself from the CI flow ('Upserts a single local analysis per branch, kept separate from any CI run') and from the unit dimension via the explicit coverage_kind split, so an agent can tell what it is without opening the schema.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines5/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

It states exactly when to reach for this tool ('the core self-correction loop for writing tests without waiting on CI'), gives the prerequisite commands for pytest-cov and vitest, and forces the 'exactly one of coverage_json vs coverage_reports' choice with a stated case for each. It also gives exclusion-style guidance ('split a multi-root upload into one call per root') and explains which coverage_kind to select.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

Try in Browser

Glama MCP Gateway

Add one secure layer between your agents and this server.

Resources