Skip to main content
Glama
agent-core-mcp

agent-core-mcp

agent-core-mcp

Deterministic computation tools for AI agents. Exact diffing, hashing, JSON querying, calendar arithmetic, regex extraction under a hard execution deadline, CSV parsing, similarity scoring and unit/base conversion — as an MCP server.

Zero dependencies. No network. Read-only.


Why this exists

Language models are excellent at generating language and unreliable at exact, reproducible mechanical computation. That is not a capability gap — it is an architectural property. Asking a probabilistic system to count, diff, hash or do calendar math guarantees a certain rate of confident wrong answers.

This server moves those operations out of the model and into a deterministic engine.

The result is not a better guess. It is a different category of answer: one that is exact and reproducible.

There is a second reason, specific to the MCP ecosystem. The most-reported problems with published servers are credential exfiltration, undisclosed shell execution, dependency trees carrying known CVEs, and servers that hang the client. A server with no network, no credentials, no execution surface, and a bounding deadline on every operation cannot exhibit any of them.

Related MCP server: Touchstone MCP Server

Guarantees

Guarantee

Meaning

Zero dependencies

No node_modules. Nothing to audit, nothing to go stale, nothing to break.

No network access

Nothing here calls out. Not one request, ever.

No credentials

Reads no tokens, no API keys, no environment variables.

Read-only

No file writes, no shell execution, no state. Stateless per call.

Deterministic

Identical input produces byte-identical output.

Bounded

Every loop and result set is capped. Regex execution runs in a worker thread that is terminated on deadline, so no pattern can hang the client.

The server publishes these as a machine-readable contract resource (agent-core://contract), so a client can verify what it is installing rather than trusting this file.

Install

npx agent-core-mcp

No install step is required to run it. Requires Node.js 18 or newer.

Available from:

Configure

Claude Code

This repository ships a .mcp.json, so cloning it is enough:

git clone https://github.com/kinbinghua-lgtm/agent-core-mcp
cd agent-core-mcp
claude   # the agent-core server is discovered automatically

Or add it to any project:

{
  "mcpServers": {
    "agent-core": {
      "command": "npx",
      "args": ["-y", "agent-core-mcp"]
    }
  }
}

Claude Desktop, Cursor, VS Code, Windsurf, Continue, Zed

Same block, in that client's MCP configuration file. No API keys. No environment variables. Nothing to sign up for.

Tools

Tool

What it does

Why the model shouldn't do it itself

diff_text

Exact line diff (LCS) with line numbers and added/removed counts

Requires exact sequence alignment; refuses oversized input rather than hanging

hash

sha256 / sha512 / sha1 / md5 / HMAC, hex + base64 + UTF-8 byte length

Cannot be computed by inspection

json_validate

Validity plus the parser message and computed line/column

Pinpointing the error by eye is error-prone

json_query

Path access like a.b[0].c; separates absent from present-but-null

Conflating those two silently causes real bugs

json_pick

Resolve many paths in one call

Cheaper than N round trips

text_stats

Code points, UTF-8 bytes, lines, words, sentences, paragraphs, unique words, top words

Counting is precisely what probabilistic generation gets wrong

date_calc

Interval in days/weeks/months/years/hours/minutes/seconds/businessDays

True calendar months, not 30-day approximations

date_add

Offset a date, calendar-correct

Month-end and leap-year handling

regex_extract

All matches with indices, numbered and named groups, under a hard deadline

A catastrophic pattern is terminated instead of hanging

regex_analyze

Static ReDoS risk assessment of a pattern

Nested quantifiers, overlapping alternation, backreferences

fuzzy_match

Rank candidates by Sorensen-Dice similarity

Deterministic scoring instead of vibes

similarity

Single similarity score, 0..1

—

parse_table

RFC 4180 CSV/TSV with quotes, escapes, embedded newlines; delimiter auto-detection

Naive comma-splitting breaks on any real CSV

convert

Length, mass, time, data size; rejects cross-family conversions

Unit errors are silent and catastrophic

base_convert

Bases 2-36 with arbitrary precision

Values above 2^53 lose precision in naive conversion

The ReDoS deadline

regex_extract accepts an optional budgetMs (default 1000, maximum 10000). Execution happens in a worker thread that is terminated when the deadline expires.

This is not a nicety. Node's regex engine cannot be interrupted, so a pattern with catastrophic backtracking blocks the main thread indefinitely. Measured growth for (a+)+$ against 'a'.repeat(n) + '!':

n

time

20

18 ms

22

70 ms

24

276 ms

26

1108 ms

Roughly 4x per two additional characters. At n=40 it does not return. In an MCP server, which runs on the client's main thread, this freezes the user's editor. Process isolation plus termination is the only real boundary.

On expiry the response says so, and tells the caller how to fix the pattern:

{
  "timedOut": true,
  "budgetMs": 300,
  "safety": {
    "risk": "high",
    "reasons": ["nested quantifier inside a repeated group — classic exponential backtracking"]
  },
  "advice": "Pattern execution exceeded 300ms and was terminated. ... Rewrite it to remove ambiguity — typically by replacing a nested quantifier such as (a+)+ with an unambiguous form such as a+ ..."
}

Argument validation

Every call is validated against the tool's own JSON Schema before dispatch: required fields, primitive types, enum membership, numeric bounds and unknown properties. A malformed call returns a specific error instead of a confident wrong answer.

This matters because clients do not reliably honour schemas. A server that silently proceeds on a malformed call is worse than one that refuses it.

Examples

Exact diff

{ "a": "line one\nline two", "b": "line one\nline 2" }

→ { "added": 1, "removed": 1, "lines": [ { "op": "equal", "aLine": 1, "bLine": 1 }, ... ] }

Big-integer conversion that stays exact

{ "value": "9007199254740993", "fromBase": 10, "toBase": 16 }

→ { "result": "20000000000001", "decimal": "9007199254740993" }

Business days between two dates

{ "from": "2026-01-05", "to": "2026-01-12", "unit": "businessDays" }

→ { "value": 5 }

Check a pattern before running it

{ "pattern": "(a+)+$" }

→ { "risk": "high", "reasons": ["nested quantifier inside a repeated group — classic exponential backtracking"] }

Absent versus null

{ "json": "{\"a\":null}", "path": "a" }

→ { "resolved": true, "found": false, "value": null, "type": "null" }

Design notes

Why stdio and not HTTP? A stdio server has no listening socket: no attack surface, no port to expose, no auth to get wrong, no data leaving the machine. For pure computation, HTTP would add risk and buy nothing.

Why no caching? Every call is stateless. Caching would introduce state, invalidation bugs and a place for data to persist. The operations are cheap enough that this is not a tradeoff.

Why refuse oversized input? An MCP server that hangs takes the client session with it. Refusing with an actionable message is strictly better than exhausting memory.

Why no dependencies at all? Every dependency is an ongoing obligation: updates, advisories, supply-chain risk, and one more reason the server might stop working. The Node standard library covers everything here.

Development

node server.cjs              # speaks MCP over stdio
node selftest.mjs            # engine verification, 35 assertions
node protocol-test.cjs       # protocol verification, 88 assertions
npm test                     # both suites

Both suites run on plain Node with no install step.

selftest.mjs checks hashing against published constants, big-integer round trips past 2^53, RFC 4180 quoting edge cases, Unicode word segmentation and calendar arithmetic. protocol-test.cjs drives the real handler through a fake transport and covers the handshake, version negotiation, every tool, argument validation, the ReDoS deadline, malformed frames, split frames, batches, concurrent request correlation and determinism.

Two bugs found by these suites, both retained as regression tests:

  • A ReDoS in the word-segmentation regex. The original textStats pattern was [\p{L}\p{N}][\p{L}\p{N}'’-]* — two adjacent, overlapping character classes. On a long letter run followed by a non-match it backtracked exponentially and hung the process. The analyzer shipped in this package did not catch it, because it statically inspects the pattern it is given and cannot see patterns written by hand in the source. The execution deadline above exists because of this.

  • Schema validation was absent. Missing required arguments were silently treated as absent values, so a caller that forgot path received missing-key instead of an error. Client-side schemas are not enforcement.

License

MIT — see LICENSE.

Available Tools

15 tools
base_convertA
Read-onlyIdempotent

Convert an integer string between bases 2 and 36 with arbitrary precision. Uses big-integer parsing, so values beyond IEEE-754 double precision (2^53) stay exact, which is exactly where naive conversion goes wrong. A leading 0b/0x/0o prefix is ignored.

Inputs: value (required), toBase (required), fromBase (required).

convertA
Read-onlyIdempotent

Convert a value between units of length, mass, time or data size. Cross-family conversions are rejected rather than silently producing nonsense. Data sizes: kb/mb/gb are decimal (1000), kib/mib/gib are binary (1024). Supported units: m, km, cm, mm, mi, yd, ft, in, nmi, kg, g, mg, t, lb, oz, s, min, h, d, b, kb, mb, gb, kib, mib, gib.

Inputs: to (required), from (required), value (required).

date_addA
Read-onlyIdempotent

Offset an ISO-8601 date by days, weeks, months, years, hours, minutes or seconds. Negative amounts subtract. Calendar-correct across month ends and leap years.

Inputs: date (required), amount (required), unit.

date_calcA
Read-onlyIdempotent

Interval between two ISO-8601 dates in days, weeks, months, years, hours, minutes, seconds or businessDays (Mon-Fri). Months and years use true calendar arithmetic, not 30/365-day approximations. All math is UTC.

Inputs: to (required), from (required), unit.

diff_textA
Read-onlyIdempotent

Compute an exact line-by-line diff between two texts using a longest-common-subsequence algorithm. Returns per-line operations (equal/del/ins) with line numbers plus added/removed/unchanged counts. Exact and reproducible; refuses oversized input rather than hanging.

Inputs: a (required), b (required), maxLines.

fuzzy_matchA
Read-onlyIdempotent

Score every candidate string against a query using the Sorensen-Dice coefficient over character bigrams and return the best matches in descending order. Deterministic. Useful for deduplication, record linkage, typo-tolerant lookup and confirming which of several candidates was meant.

Inputs: needle (required), haystack (required), topN, threshold.

hashA
Read-onlyIdempotent

Compute a cryptographic hash of a UTF-8 string. Returns hex and base64 digests plus the UTF-8 byte length. Supports sha256 (default), sha512, sha1, md5, and HMAC variants via hmacKey. Use for content fingerprints, deduplication and integrity checks.

Inputs: text (required), algo, hmacKey.

json_pickA
Read-onlyIdempotent

Resolve several paths against one JSON document in a single call. Cheaper than issuing many json_query calls when you need multiple fields.

Inputs: json (required), paths (required).

json_queryA
Read-onlyIdempotent

Extract a value from a JSON document by path, e.g. "a.b[0].c" or "$.items[3].name". Reports resolved (did the path reach a location) separately from found (is the value non-null), so absent is distinguishable from present-but-null. Failure types are specific: missing-key, out-of-range, not-an-array, not-an-object.

Inputs: json (required), path (required).

json_validateA
Read-onlyIdempotent

Check whether a string is valid JSON. On failure returns the parser message plus the computed line and column of the error. On success returns the top-level shape. Distinguishes valid-but-empty-object from invalid.

Inputs: text (required), describeTopLevel.

parse_tableA
Read-onlyIdempotent

Parse delimited text into a header plus rows, handling quoted fields, escaped quotes, embedded delimiters and embedded newlines (RFC 4180 style). If no delimiter is given, the most frequent candidate on the first line is chosen and reported back. Use instead of splitting on commas, which breaks on any real CSV.

Inputs: text (required), maxRows, delimiter, hasHeader.

regex_analyzeA
Read-onlyIdempotent

Statically analyse a regular expression for catastrophic backtracking (ReDoS): nested quantifiers, overlapping alternation inside repeated groups, backreferences under quantifiers, excessive wildcards. Returns a risk level and the specific reasons. The pattern is not executed.

Inputs: pattern (required).

regex_extractA
Read-onlyIdempotent

Apply a regular expression and return every match with its index, numbered capture groups and named groups. Iteration and match counts are hard-capped so a pathological pattern cannot hang the host. The response includes a ReDoS risk assessment of the pattern.

Inputs: text (required), pattern (required), flags, budgetMs, +1 more.

similarityA
Read-onlyIdempotent

Sorensen-Dice similarity of two strings, from 0 (no shared character bigrams) to 1 (identical). One deterministic comparison.

Inputs: a (required), b (required).

text_statsA
Read-onlyIdempotent

Exact text statistics: Unicode code points, UTF-8 bytes, lines, non-empty lines, words, sentences, paragraphs, unique words, average word length and most frequent words. Word segmentation is Unicode-aware so non-Latin scripts are counted correctly. Use whenever a count must be exact.

Inputs: text (required), topN.

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections.

Loading tool schema changelog…

    TDQS

    A4/5.0

    Scored across 15 tools

    Disambiguation5/5

    Each tool targets a distinct operation, and the few potential pairs are explicitly differentiated in the descriptions: json_query (single path) vs json_pick (multiple paths), date_calc (interval) vs date_add (offset), regex_extract (apply) vs regex_analyze (static ReDoS analysis), and fuzzy_match (many candidates) vs similarity (one comparison). An agent can reliably pick the right tool for each intent.

    Naming Consistency4/5

    All names use consistent snake_case, mostly following a noun_verb or verb_noun pattern (json_validate, date_add, regex_extract, parse_table, base_convert). A few single-word nouns (hash, similarity, convert) break the strict action-oriented pattern slightly, but the set is uniformly readable.

    Tool Count5/5

    Fifteen tools sit comfortably in the well-scoped range, and each one covers a genuinely distinct capability (hashing, diffing, JSON, dates, regex, similarity, delimited parsing, unit and base conversion). No tool feels redundant or filler.

    Completeness4/5

    As a general text/data utility toolkit it covers its sub-domains well: JSON validate/query/pick, date arithmetic both directions, regex matching plus safety analysis, similarity, parsing and conversions. Minor gaps remain within sub-domains (e.g. no JSON formatting/minify or general string encoding/decoding), but core workflows have no dead ends.

    Maintenance

    ActivityStale
    ResponsivenessNo recent community issues

    Related MCP Connectors

    Related MCP Servers

    • A
      license
      Not graded
      quality
      C
      maintenance
      Provides over 500 deterministic tools for math, conversions, validation, hashing, and more, enabling AI agents to perform accurate calculations and data transformations without hallucination.
      1
      MIT
    • A
      license
      Not graded
      quality
      D
      maintenance
      Provides deterministic, verifiable text/code/measurement utilities for AI agents, enabling tasks like unit conversion, citation formatting, diffing, proofreading, readability scoring, and syntax checking with re-executable proof.
      MIT
    • A
      license
      Not graded
      quality
      B
      maintenance
      Provides exact, deterministic tools for math, dates, units, validation, and more to AI agents, returning precise answers with explicit assumptions and warnings instead of model guesses.
      MIT
    • A
      license
      B
      quality
      B
      maintenance
      Enables AI agents to perform accurate local computations including arbitrary-precision math, date handling, unit conversion, subnet calculations, encoding, hashing, and text analysis, all without network calls or API keys.
      27
      MIT