Skip to main content
Glama
kyungseopk1m

semver-checks

by kyungseopk1m
OverviewSchemaSourceRelated ServersDiscussionsAdmin
TypeScript
Local

semver_snapshot

Extract a TypeScript package's public API surface as JSON from a filesystem path, git ref, or npm spec, without comparing it to anything. Use the snapshot to see what a package exports before deciding a version bump.

Instructions

Extract the public API surface of a TypeScript project as JSON, without comparing it to anything. Use it to see what a package exports; use semver_compare to decide a bump. The source can be a filesystem path, a git ref, or an npm spec, the same three forms semver_compare takes, with the same network and temp-directory behaviour. Returns {"entrypoints": {: {: }}}, with each symbol's full type shape in place of its kind when "detail" is set. Symbols stop at the "maxBytes" budget, and an "omitted" field then gives the number left out and the total. A source whose surface comes back empty is reported as an analysis_failed error, not as an empty result; pass "entry" to point at the declaration file.

Input Schema

NameRequiredDescriptionDefault
pathNoProject source: a filesystem path, a git ref, or an npm spec such as "lodash@4.17.21". Defaults to current directory..
entryNoEntry file relative to project root (e.g. "src/index.ts"). Pass an array or a comma-separated string for a package with several entry points.
detailNoInclude each symbol's full type shape instead of just its kind. A shape runs a median of about 370 bytes and a wide interface tens of kilobytes, against about 35 for a name and a kind, so a large package will hit the byte budget after a few dozen symbols.
pathAsNoForce "path" to be treated as a filesystem path, a git ref, or an npm spec. "ref" is an accepted spelling of "git". Only needed when auto-detection would read the input as the wrong kind.
maxBytesNoByte budget for the symbols in the response (default 40000). Symbols are included while it lasts, and an "omitted" field then reports how many were left out along with the total. No symbol is exempt: under "detail" a single wide interface can cost tens of kilobytes, so a budget smaller than that returns no symbols and says so rather than overshooting. Only the entrypoint keys and the "omitted" field sit outside the budget, a few hundred bytes.
installDepsNoInstall dependencies before analysis. In a local path with no node_modules this runs "npm install --ignore-scripts" in that directory, and adds @types/node there if it is missing. Only a local path needs it: a git ref is always installed in its temp copy.

Schema Changelog

Changes observed during successful MCP inspections.

  1. Changed1 schema field changedv0.15.2
    • changedInput schema / properties / installDeps / description
      Previous value: -"Install dependencies before analysis"New value: +"Install dependencies before analysis. In a local path with no node_modules this runs \"npm install --ignore-scripts\" in that directory, and adds @types/node there if it is missing. Only a local path needs it: a git ref is always installed in its temp copy."
  2. First observedv0.1.0

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 behavioral burden well: it discloses non-comparison behavior, source forms, shared network/temp behavior with semver_compare, the omitted-symbol budget behavior, and that an empty surface becomes an analysis_failed error. It does not explicitly restate side-effect implications such as installDeps running npm install, though that is covered in the schema.

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?

The description is dense and front-loaded with the core action and sibling routing. It is longer than ideal but nearly every sentence adds operational detail, though some clauses could be more cleanly structured.

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 complex six-parameter tool with no annotations and no output schema, the description is complete enough to call correctly. It explains the return shape, budget truncation, error behavior, source handling, and the role of entry.

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 100%, so the baseline is 3. The description still adds value by tying detail, maxBytes, and entry to observable behavior: full type shapes, budget truncation with omitted counts, and pointing at a declaration file when the surface is empty.

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 description states a specific verb and resource: extract the public API surface of a TypeScript project as JSON. It sharply distinguishes this from the sibling by saying it does not compare and by naming semver_compare as the tool for deciding a bump.

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 gives explicit usage: see what a package exports with this tool, and use semver_compare to decide a bump. It also explains source forms and the empty-surface error, which tells the agent when to adjust inputs rather than treating the result as valid.

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

Deploy Server

Other Tools