@forecall/lint

Scores how well the tools of an MCP server are described for the AI agents that read them: each tool out of 100 on its purpose, when to use it, its arguments, its return value, its constraints and examples, and the server as a whole (too many tools, near-identical descriptions, shared descriptions). It is the linter behind forecall.dev and the forecall command, and runs anywhere JavaScript does, with no dependencies and no network.

npm install @forecall/lint

import { readFile } from "node:fs/promises";
import { lintToolsList } from "@forecall/lint";

const result = lintToolsList(await readFile("tools.json", "utf8"));
if (result.ok) {
  console.log(result.report.scoreAvg);
  for (const tool of result.report.tools) console.log(tool.name, tool.score, tool.issues);
} else {
  console.error(result.error.code);
}

API

• lintToolsList(text): reads a tools/list in any accepted shape (an array of tools, { "tools": [...] }, or a JSON-RPC { "result": { "tools": [...] } }) and scores it. Returns { ok: true, report }, or { ok: false, error } when the text cannot be read. A file written by forecall dump also carries the server's instructions, which are checked too (a bare tools/list cannot say whether the server has any).
• parseToolsList(text): the reading alone. Returns { ok: true, tools, handshake?, shape? } or { ok: false, error }; handshake is there for a dump. A list of entries that is not a tools/list, such as search results or endpoints ({ "entries" | "results" | "items" | "endpoints": [...] }, or a bare array, each element with a name, operationId, id, title or path and a description, summary, text or snippet; an OpenAPI-style parameters array or a schema object as the arguments), is read into tools and scored the same way, with shape: "entries". The name is made a slug that fits a tool's name, the original kept as the title.
• LINT_VERSION: the version of the scoring rules. Compare scores only within one version; what each version changed is in the repository's CHANGELOG.md.
• The types: Tool, LintReport, ToolScore, ToolIssue, ServerIssue, ToolsListError, Handshake, LintOptions and the others the functions use.

These follow semver. What every issue code means is at forecall.dev/en/docs/reading-scores.

@forecall/lint/internal/* is for Forecall's own apps. It may change in any version, minor or patch: do not depend on it.

Source and issues

The source is at github.com/forecall/forecall-cli (packages/lint). Report bugs in its issues, and vulnerabilities as its SECURITY.md says. Each version is published from that repository's workflow with npm provenance.

License

Apache-2.0. Copyright 2026 Mirai Studio, Inc.