{"_id":"@casualtheorics/argdown-mcp","_rev":"2-adb393f127b13c70a3fceb03051da8d6","name":"@casualtheorics/argdown-mcp","dist-tags":{"latest":"0.3.0"},"versions":{"0.2.0":{"name":"@casualtheorics/argdown-mcp","version":"0.2.0","keywords":["mcp","model-context-protocol","argdown","argumentation","claude"],"author":{"name":"Casual Theorics"},"license":"MIT","_id":"@casualtheorics/argdown-mcp@0.2.0","maintainers":[{"name":"kellenff","email":"kellen+npm@kellenfujimoto.com"}],"homepage":"https://github.com/casualtheorics/argdown-mcp#readme","bugs":{"url":"https://github.com/casualtheorics/argdown-mcp/issues"},"os":["!win32"],"bin":{"argdown-mcp":"dist/server.js"},"dist":{"shasum":"b811e6263b6fc8a34a545f6ecb76ea75f5a6d846","tarball":"https://registry.npmjs.org/@casualtheorics/argdown-mcp/-/argdown-mcp-0.2.0.tgz","fileCount":4,"integrity":"sha512-DaCh0TcFtmJXvwmzKX8RJZA3NoLsT4De1e9cwhpu4bieTc7flRij4rlbptvVh641T1cojk/W9nlZL8kJLdXvAA==","signatures":[{"sig":"MEUCIQDGeLd0QYqMBvckBh2Z7a4zAKsWA8GfmTdHeu5adwY9IQIgKqsZh0YCixxBZPkVaAvfuqhJdjFZ/gPmHZTVeskcqGs=","keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U"}],"unpackedSize":6173019},"type":"module","engines":{"node":">=24"},"gitHead":"9ffcffd81283b2033baf8ad53d089cb371433224","scripts":{"dev":"tsup --watch","test":"vitest run","build":"tsup","smoke":"bash scripts/smoke.sh","release":"yarn npm publish --access public","typecheck":"tsc --noEmit","bundle-sanity":"bash scripts/bundle-sanity.sh","prepublishOnly":"yarn build && yarn typecheck && yarn test"},"_npmUser":{"name":"kellenff","email":"kellen+npm@kellenfujimoto.com"},"repository":{"url":"git+https://github.com/casualtheorics/argdown-mcp.git","type":"git"},"_npmVersion":"11.12.1","description":"stdio MCP server wrapping the Argdown argumentation toolchain (parse + JSON export + Dung grounded extension)","directories":{},"_nodeVersion":"24.15.0","dependencies":{},"publishConfig":{"access":"public"},"_hasShrinkwrap":false,"packageManager":"yarn@4.14.1","devDependencies":{"zod":"^3","tsup":"^8","vitest":"^4.1.6","typescript":"^5","@types/node":"^24","@argdown/core":"^2.0.1","@argdown/node":"^2.0.3","@yarnpkg/sdks":"^3.2.3","@modelcontextprotocol/sdk":"^1.29.0","@rollup/rollup-darwin-arm64":"^4.60.3"},"_npmOperationalInternal":{"tmp":"tmp/argdown-mcp_0.2.0_1778793498720_0.9351153046962593","host":"s3://npm-registry-packages-npm-production"}},"0.3.0":{"name":"@casualtheorics/argdown-mcp","version":"0.3.0","description":"stdio MCP server wrapping the Argdown argumentation toolchain (parse + JSON export + Dung grounded extension)","keywords":["argdown","argumentation","claude","mcp","model-context-protocol"],"homepage":"https://github.com/casualtheorics/argdown-mcp#readme","bugs":{"url":"https://github.com/casualtheorics/argdown-mcp/issues"},"license":"MIT","author":{"name":"Casual Theorics"},"repository":{"type":"git","url":"git+https://github.com/casualtheorics/argdown-mcp.git"},"bin":{"argdown-cli":"dist/cli.js","argdown-mcp":"dist/server.js"},"os":["!win32"],"type":"module","publishConfig":{"access":"public"},"scripts":{"build":"tsup","dev":"tsup --watch","typecheck":"tsc --noEmit","test":"vitest run","smoke":"bash scripts/smoke.sh","smoke:deno":"bash scripts/smoke-deno.sh","bundle-sanity":"bash scripts/bundle-sanity.sh","lint":"oxlint","lint:fix":"oxlint --fix","format":"oxfmt","format:check":"oxfmt --check","prepublishOnly":"yarn build && yarn typecheck && yarn lint && yarn format:check && yarn test","release":"yarn npm publish --access public"},"devDependencies":{"@argdown/core":"2.0.1","@argdown/node":"2.0.3","@modelcontextprotocol/sdk":"1.29.0","@rollup/rollup-darwin-arm64":"4.60.3","@types/node":"24.12.4","@yarnpkg/sdks":"3.2.3","oxfmt":"0.51.0","oxlint":"1.66.0","oxlint-tsgolint":"0.23.0","tsup":"8.5.1","typescript":"5.9.3","vitest":"4.1.6","zod":"3.25.76"},"engines":{"node":">=24"},"packageManager":"yarn@4.14.1","gitHead":"ef9cef4fc3c468249300c7aa60270cc1a9c4b6b8","_id":"@casualtheorics/argdown-mcp@0.3.0","_nodeVersion":"24.15.0","_npmVersion":"11.12.1","dist":{"integrity":"sha512-2MTPf6R1NUIJT3r9SYGCVJFOgt/SB/db5pHPlno5piIu+YYcDyHAqotUZWQzozuvAzqdtj/9GZRO9BSRQd4tkg==","shasum":"1a217396a0d727811c80100d6654f6e1c266f78c","tarball":"https://registry.npmjs.org/@casualtheorics/argdown-mcp/-/argdown-mcp-0.3.0.tgz","fileCount":5,"unpackedSize":11602619,"signatures":[{"keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U","sig":"MEQCIDe4nR0yYWkLBKca+1OBV+UDtybmwZ6mv/xkIrs78PVrAiAZLa1mADP6jDxaK/1dXPAnugrEo4QGInfQCE5qB+KxMg=="}]},"_npmUser":{"name":"kellenff","email":"kellen+npm@kellenfujimoto.com"},"directories":{},"maintainers":[{"name":"kellenff","email":"kellen+npm@kellenfujimoto.com"}],"_npmOperationalInternal":{"host":"s3://npm-registry-packages-npm-production","tmp":"tmp/argdown-mcp_0.3.0_1779424401861_0.2632957638873765"},"_hasShrinkwrap":false}},"time":{"created":"2026-05-14T21:18:18.648Z","modified":"2026-05-22T04:33:22.252Z","0.2.0":"2026-05-14T21:18:18.937Z","0.3.0":"2026-05-22T04:33:22.117Z"},"bugs":{"url":"https://github.com/casualtheorics/argdown-mcp/issues"},"author":{"name":"Casual Theorics"},"license":"MIT","homepage":"https://github.com/casualtheorics/argdown-mcp#readme","keywords":["argdown","argumentation","claude","mcp","model-context-protocol"],"repository":{"type":"git","url":"git+https://github.com/casualtheorics/argdown-mcp.git"},"description":"stdio MCP server wrapping the Argdown argumentation toolchain (parse + JSON export + Dung grounded extension)","maintainers":[{"name":"kellenff","email":"kellen+npm@kellenfujimoto.com"}],"readme":"# `@casualtheorics/argdown-mcp`\n\n`argdown-mcp` is a sandboxed stdio MCP server that parses [Argdown](https://argdown.org/) documents and computes Dung\ngrounded extensions — which arguments survive once every attack is resolved — for language-model agents. It runs\nunder [Deno](https://deno.com) with every runtime permission denied (no filesystem, no network, no subprocess), so a\nmodel-invoked tool cannot escalate beyond stdio. Reasoning is grounded in named primitives: Dung's abstract\nargumentation framework and Caminada's three-valued labelling. A companion Claude Code plugin extends this with\nPollock's defeater frame and Walton's argument schemes.\n\n## At a glance\n\n| | |\n| -------------------- | ------------------------------------------------------------------------------------------------- |\n| **Surface** | stdio MCP server — three tools (`parse`, `export_json`, `dung_extensions`) |\n| **Sandbox** | Deno deny-by-default — file, network, subprocess, FFI, OS info, env all denied |\n| **Theory** | Dung (1995) abstract argumentation + Caminada (2006) three-valued labelling |\n| **Runtime** | Deno ≥2.0 (recommended) · Node ≥24 (fallback) · Linux + macOS only |\n| **Companion plugin** | `@casualtheorics/argdown-plugin` — 7 Claude Code skills routing natural language to the server |\n| **Out of scope** | Rendering (HTML / SVG / dot / PDF), non-grounded Dung semantics, statement-level attacks, Windows |\n\n## Quickstart\n\n```bash\nclaude mcp add --scope user argdown -- deno run --no-config --no-prompt --deny-read --deny-write --deny-net --ignore-env --deny-sys --deny-run --deny-ffi npm:@casualtheorics/argdown-mcp\n```\n\nThat one command registers the server with Claude Code under the strict Deno permission sandbox. No `yarn install`, no\n`node_modules`, no local build. Deno fetches the npm bundle and runs it with every dangerous permission denied at\nlaunch.\n\nOther MCP clients: see [Install (per MCP client)](#install-per-mcp-client) below.\n\n## Sandbox\n\nMCP servers run as long-lived child processes of an LLM client. A typical Node-launched MCP server inherits its parent's\nambient permissions — full filesystem read, network egress, subprocess spawn — which means a tool the model can invoke\nalso has those permissions. This server's blessed launch denies all of them upfront:\n\n```\ndeno run --no-config --no-prompt\n --deny-read --deny-write --deny-net\n --ignore-env --deny-sys --deny-run --deny-ffi\n npm:@casualtheorics/argdown-mcp\n```\n\n| Flag | What it prevents |\n| -------------- | ---------------------------------------------------- |\n| `--deny-read` | Reading any host file |\n| `--deny-write` | Writing any host file |\n| `--deny-net` | Outbound network requests |\n| `--ignore-env` | Reading process environment variables |\n| `--deny-sys` | Querying OS info (uid, hostname, network interfaces) |\n| `--deny-run` | Spawning subprocesses |\n| `--deny-ffi` | Loading native libraries |\n| `--no-prompt` | Interactive permission elevation at runtime |\n| `--no-config` | Reading `deno.json` / project config from CWD |\n\nCI verifies the bundle works under this exact profile on every push to `main`: see [\n`scripts/smoke-deno.sh`](./scripts/smoke-deno.sh), invoked by the `Deno runtime smoke` job in [\n`.github/workflows/ci.yml`](./.github/workflows/ci.yml). The deny set is not aspirational documentation; it is the\nruntime under which the parse / JSON-export / Dung tools are smoke-tested before release.\n\nThe MCP input `kind: \"file\"` (filesystem path) is **deprecated for model use** because honoring it requires loosening\n`--deny-read`. Pass Argdown as inline `source` instead. Operator-facing CLI use can still pass `--path`.\n\n## Tools\n\n| Tool | `readOnlyHint` | `openWorldHint` | Side effects |\n| ----------------- | :------------: | :-------------: | --------------------------------------- |\n| `parse` | `true` | `false` | None — pure function over inline source |\n| `export_json` | `true` | `false` | None |\n| `dung_extensions` | `true` | `false` | None |\n\nAll three accept the same input shape:\n\n```json\n{\n \"kind\": \"inline\",\n \"source\": \"\"\n}\n```\n\n### `parse`\n\nParses an Argdown document and returns a structural summary plus diagnostics.\n\n**Returns:**\n\n- A summary line with statement, argument, and section counts.\n- A diagnostic block listing any lexer/parser errors with `line:col` positions, and any plugin exceptions.\n- A `(not valid Argdown)` hint when the input parses but contains only synthetic (`Untitled N`) statements with no\n relations, arguments, or sections — the Argdown parser is permissive, so this heuristic catches \"definitely not\n Argdown\" inputs.\n\n`isError: true` is set when any of the following hold: lexer or parser errors are present, a plugin threw an exception,\nor the document parses to only synthetic anonymous statements with no relations, arguments, or sections.\n\n### `export_json`\n\nSame as `parse`, but also returns the full `IArgdownResponse.json` payload in a fenced JSON block. Statements,\narguments, relations, and sections come through as structured data.\n\n### `dung_extensions`\n\nComputes the grounded extension\nunder [Dung's abstract argumentation framework](https://plato.stanford.edu/entries/argument/) — which arguments survive\nonce every attack has been resolved — using Caminada's three-valued labelling algorithm.\n\n**Returns:**\n\n- A summary line: `Grounded extension: N IN, M OUT, K UNDEC over A arguments and R attacks.`\n- A fenced JSON block with the full partition:\n\n```json\n{\n \"extension\": {\n \"in\": [\"...\"],\n \"out\": [\"...\"],\n \"undec\": [\"...\"]\n },\n \"argumentCount\": 0,\n \"attackCount\": 0\n}\n```\n\n**Label semantics:**\n\n- **IN** — accepted: every attacker of this argument is OUT.\n- **OUT** — defeated: at least one attacker is IN.\n- **UNDEC** — undecided: caught in an unresolved cycle.\n\n**Scope:**\n\n- Only **argument-to-argument** attack relations are considered (written `\\n - ` in Argdown). Statement-level\n attacks (`[s1]\\n - [s2]`) are intentionally ignored — Dung's framework is abstract over arguments; lifting statement\n attacks belongs to a structured-argumentation layer (ASPIC+, ABA), which is out of scope.\n- Only the **grounded** semantics is computed. Preferred, stable, complete, semi-stable, and ideal semantics are out of\n scope for v0.2.\n- Undercuts (`relationType: \"undercut\"`) target inference nodes, not arguments, and are filtered out.\n- A self-attacker with no external defeater is UNDEC; with an IN external defeater, it is OUT.\n\n### Worked example\n\nA four-argument reinstatement chain — the classic test of whether a Dung implementation handles defeat propagation\ncorrectly.\n\n**Input:**\n\n```argdown\n: claim a.\n - \n\n: claim b.\n - \n\n: claim c.\n - : claim d.\n```\n\nThe chain reads: `D` attacks `C`, `C` attacks `B`, `B` attacks `A`.\n\n**`dung_extensions` response:**\n\n```\nGrounded extension: 2 IN, 2 OUT, 0 UNDEC over 4 arguments and 3 attacks.\nExtension:\n```\n\n```json\n{\n \"extension\": {\n \"in\": [\"B\", \"D\"],\n \"out\": [\"A\", \"C\"],\n \"undec\": []\n },\n \"argumentCount\": 4,\n \"attackCount\": 3\n}\n```\n\n`D` is unattacked → **IN**. `C` is attacked by `D` (IN) → **OUT**. `B`'s only attacker `C` is now OUT → **IN** _(\nreinstated)_. `A` is attacked by `B` (IN) → **OUT**.\n\nA three-argument odd cycle, by contrast, declines to decide:\n\n**Input:**\n\n```argdown\n: claim a.\n - \n\n: claim b.\n - \n\n: claim c.\n - \n```\n\n**`dung_extensions` response:**\n\n```\nGrounded extension: 0 IN, 0 OUT, 3 UNDEC over 3 arguments and 3 attacks.\n```\n\nNo argument can be labelled without circularly depending on another. The grounded semantics leaves all three **UNDEC** —\nthe honest answer for a cycle of mutually attacking arguments.\n\n## Theory\n\nThe server's `dung_extensions` tool implements Dung's grounded semantics from _On the acceptability of arguments and its\nfundamental role in nonmonotonic reasoning, logic programming and n-person games_ (Phan Minh Dung, 1995). Labels are\nassigned by the iterative fixpoint described in Caminada's _On the issue of reinstatement in argumentation_ (2006): IN,\nOUT, and UNDEC partition the argument set such that every IN argument has all attackers OUT, and every OUT argument has\nat least one IN attacker.\n\nThe companion plugin (next section) carries additional theoretical scaffolding:\n\n- **Pollock** — rebutting vs. undercutting defeaters. A rebutter attacks a conclusion directly; an undercutter attacks\n the inferential link between premises and conclusion. Used by `rebut-argument`.\n- **Walton** — argument schemes and critical questions. A catalogue of recurring inference patterns (expert opinion,\n cause-to-effect, analogy, etc.) each with associated critical questions that probe weak points. Used by\n `rebut-argument` and (planned) `detect-fallacies`.\n- **Toulmin** — claim / data / warrant / backing. Roles assigned to statements when converting prose to Argdown. Used by\n `extract-argument`.\n- **Govier** — the **A**cceptability / **R**elevance / **G**rounds triad. Three axes on which to audit a premise. Used\n by `find-unsupported-premises`.\n\nPlugin skill documentation cites the primary sources directly: see [\n`argdown-plugin/skills/references/argumentation-theory.md`](./argdown-plugin/skills/references/argumentation-theory.md).\n\n## Companion Claude Code plugin\n\n[`@casualtheorics/argdown-plugin`](./argdown-plugin) ships seven skills that route natural-language requests to the MCP\ntools above. Claude Code activates them automatically by trigger phrase.\n\n| Skill | Triggers (excerpt) |\n| --------------------------- | ------------------------------------------------------------------ |\n| `validate-argdown` | \"validate this argdown\" · \"check argdown syntax\" |\n| `find-unsupported-premises` | \"find weak points\" · \"find gaps in the support\" |\n| `trace-argument` | \"trace why X follows\" · \"what supports Y\" |\n| `rebut-argument` | \"rebut this argument\" · \"steelman a counter\" |\n| `extract-argument` | \"extract the argument from this prose\" · \"convert this to argdown\" |\n| `argdown-to-prose` | \"summarise this argdown\" · \"explain this argument map in words\" |\n| `dung-extensions` | \"compute the grounded extension\" · \"which arguments survive\" |\n\nInstall:\n\n```bash\nclaude plugin install @casualtheorics/argdown-plugin\n```\n\nThe plugin's bundled `.mcp.json` registers `@casualtheorics/argdown-mcp` through Deno with the deny-by-default sandbox\nshown above. No separate setup beyond having `deno` ≥2.0 on `PATH`. See [`MARKETPLACE.md`](./MARKETPLACE.md) for the\nfull plugin documentation.\n\n## Install (per MCP client)\n\n### Claude Code\n\n```bash\nclaude mcp add --scope user argdown -- deno run --no-config --no-prompt --deny-read --deny-write --deny-net --ignore-env --deny-sys --deny-run --deny-ffi npm:@casualtheorics/argdown-mcp\n```\n\n### Claude Desktop\n\nEdit `claude_desktop_config.json`:\n\n```json\n{\n \"mcpServers\": {\n \"argdown\": {\n \"command\": \"deno\",\n \"args\": [\n \"run\",\n \"--no-config\",\n \"--no-prompt\",\n \"--deny-read\",\n \"--deny-write\",\n \"--deny-net\",\n \"--ignore-env\",\n \"--deny-sys\",\n \"--deny-run\",\n \"--deny-ffi\",\n \"npm:@casualtheorics/argdown-mcp\"\n ]\n }\n }\n}\n```\n\n### Cursor / VS Code / Cline / other MCP clients\n\nUse the same `command` + `args` pair as the Claude Desktop block, transposed into the client's MCP server configuration\nformat. The strict Deno profile is identical across clients.\n\n### Node fallback (compatibility only)\n\n```bash\nnpx @casualtheorics/argdown-mcp\n```\n\nNode ≥24 runs the same bundle but provides no runtime permission sandbox. Reserve this for trusted local use; the\nrecommended posture for model-attached MCP remains the Deno launch above.\n\n## CLI (no MCP required)\n\nThe package also ships an `argdown-cli` binary exposing the same three patterns directly from the shell.\n\n```bash\n# Inline source\nargdown-cli parse --source \"[a]: hello\n + [b]: world\"\n\n# Compute the Dung grounded extension\nargdown-cli dung --path debate.argdown\n\n# Stdin (use the bare `-` sentinel)\ncat doc.argdown | argdown-cli export-json -\n```\n\n| CLI command | MCP tool |\n| ------------------------- | ----------------- |\n| `argdown-cli parse` | `parse` |\n| `argdown-cli export-json` | `export_json` |\n| `argdown-cli dung` | `dung_extensions` |\n\nPass exactly one of `--source `, `--path `, or `-` (stdin). Add `--json` to emit the full MCP envelope (\n`{ content, isError? }`) verbatim — useful for piping into `jq`. The MCP path input is deprecated; the direct CLI still\nsupports `--path` because the operator chose to invoke it.\n\nExit codes: `0` success · `1` the shaped result is flagged as an error · `2` argument-validation failure.\n\n## Architecture\n\n```mermaid\nflowchart LR\n Source[\"Argdown source
(kind: inline)\"] --> Parser[\"ParserPlugin\"]\n Parser --> Model[\"ModelPlugin\"]\n Model --> Route{\"Tool\"}\n Route -->|\" parse \"| Shape[\"shapeResponse\"]\n Route -->|\" export_json \"| Export[\"JSONExportPlugin\"]\n Export --> Shape\n Route -->|\" dung_extensions \"| Dung[\"dungGrounded
(Caminada labelling)\"]\n Dung --> ShapeDung[\"shapeDungResponse\"]\n Shape --> Envelope[\"MCP tool result\"]\n ShapeDung --> Envelope\n```\n\nThe server registers three `@argdown/core` plugins: `ParserPlugin`, `ModelPlugin`, and `JSONExportPlugin`. Rendering\nplugins (`html`, `svg`, `dot`, `pdf`), selection/color/tag/group plugins, and `argdown.config.json` discovery are\nintentionally excluded. The goal is a minimal, deterministic parse surface.\n\nThe package ships as a single self-contained `dist/server.js` (~6 MB) with no runtime npm dependencies. `@argdown/core`,\n`@argdown/node`, the MCP SDK, and Zod are bundled by tsup; a `createRequire` ESM shim satisfies the CJS dependencies\nthat `@argdown/node` pulls in transitively.\n\nThe wire input schema is a flat `{ kind, source?, path? }` object rather than a discriminated union, because the MCP\nSDK's `normalizeObjectSchema` does not accept `z.discriminatedUnion(...)` — it silently emits an empty schema to\nclients. Handler-side validation enforces the kind / field invariant.\n\n## Non-goals\n\n| Excluded | Why |\n| -------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |\n| Rendering (HTML, SVG, dot, PDF) | This is a _headless_ parse and reasoning surface. Rendering is `@argdown/cli`'s job. |\n| Preferred / stable / complete / semi-stable / ideal extensions | Out of scope for v0.2. Grounded is sufficient for the unique-acceptance case that motivates LLM tool use. |\n| Statement-level attack lifting | Argdown's `[s1] - [s2]` syntax is not auto-lifted to argument attacks. Lifting belongs to a structured-argumentation layer (ASPIC+, ABA), not to Dung. |\n| `kind: \"file\"` for model-invoked calls | Requires loosening `--deny-read`. The CLI still accepts `--path` for operator use. |\n| Ambient permissions | The blessed runtime denies file, network, subprocess, FFI, OS info, and env. Re-enabling any of them re-introduces the risk the project exists to eliminate. |\n| Windows | `package.json` sets `\"os\": [\"!win32\"]`. Cross-platform Deno support exists, but the Node compatibility path has not been verified on Windows and the CI matrix does not cover it. |\n\n## Platform & runtime support\n\nLinux and macOS. Windows is not supported (`package.json` sets `\"os\": [\"!win32\"]` and will refuse to install).\n\nThe recommended runtime is Deno ≥2.0. Node ≥24 is supported as a fallback for trusted local use, not as the recommended\nMCP deployment mode.\n\n## Troubleshooting\n\n- **`@import` through MCP path mode is deprecated.** Strict Deno launches deny file reads, so `kind: \"file\"` cannot load\n importer files or imports. Expand imports outside MCP and pass the complete Argdown text as inline `source`.\n- **`@import` cycles** are detected by `@argdown/node`'s `IncludePlugin` and surfaced in `response.exceptions`. The\n server will not hang.\n- **`(not valid Argdown)` hint** appears when the input parses successfully but produces only synthetic `Untitled N`\n statements with no relations. This is the server's heuristic for catching non-Argdown content passed to\n `kind: \"inline\"`.\n\n## Contributing\n\nSee [`CONTRIBUTING.md`](./CONTRIBUTING.md) for prerequisites, workflow commands, and the release procedure.\n\n## License\n\nMIT. See the [`LICENSE`](./LICENSE) file.\n","readmeFilename":"README.md"}