{"_id":"@bub0lehich/skill-state-mcp-server","_rev":"2-4f702bc22b695aca207a2dfe0a5dfd01","name":"@bub0lehich/skill-state-mcp-server","dist-tags":{"latest":"1.0.1"},"versions":{"1.0.0":{"name":"@bub0lehich/skill-state-mcp-server","version":"1.0.0","keywords":["mcp","model-context-protocol","skill-state","agent","ai-agents","llm","context-optimization","state-machine"],"license":"MIT","_id":"@bub0lehich/skill-state-mcp-server@1.0.0","maintainers":[{"name":"bub0lehich","email":"kapetanamerika77@gmail.com"}],"homepage":"https://github.com/Derzkiyboomchik/skill-state-mcp-server#readme","bugs":{"url":"https://github.com/Derzkiyboomchik/skill-state-mcp-server/issues"},"bin":{"skill-state-mcp-server":"dist/index.js"},"dist":{"shasum":"0389fc9668b8177cffb8bbad7fef97267421c26f","tarball":"https://registry.npmjs.org/@bub0lehich/skill-state-mcp-server/-/skill-state-mcp-server-1.0.0.tgz","fileCount":19,"integrity":"sha512-/aZWnmgs9w/lvIijvxRG/g47SHAA9KGQwhgYRun0YKsCUKADSIiOj9WHGNaJ4+AU64QOJIPSmjLmP4XCt5Hw6w==","signatures":[{"sig":"MEUCIQC1PRWrSce8S0PVR9Iw+B9QtPlFN8zGIrRhuDRAesXX1wIgaMG4drRqBiADKCayJQhCwk3s3V4bPInQIuvyAx+KCKg=","keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U"}],"unpackedSize":1473672},"main":"./dist/index.js","type":"module","types":"./dist/index.d.ts","gitHead":"47b206cbf8b99cd849cf00a6ca8680128f99021a","scripts":{"dev":"tsx watch index.ts --http --port 3211","demo":"tsx demo/demo-client.ts","test":"tsx --test tests/*.test.ts","build":"tsc -p tsconfig.build.json","start":"node dist/index.js","demo:bun":"bun demo/demo-client.ts","start:bun":"bun index.ts","start:dev":"tsx index.ts","typecheck":"tsc --noEmit","start:http":"node dist/index.js --http --port 3211","prepublishOnly":"npm run build"},"_npmUser":{"name":"bub0lehich","email":"kapetanamerika77@gmail.com"},"repository":{"url":"git+https://github.com/Derzkiyboomchik/skill-state-mcp-server.git","type":"git"},"_npmVersion":"11.19.0","description":"MCP runtime for the SKILL.state architecture (arXiv:2608.26263) — replaces append-only conversational history with an explicit, mutable execution state (P, Σ, O).","directories":{},"_nodeVersion":"24.14.1","dependencies":{"zod":"^3.25.0","@modelcontextprotocol/sdk":"^1.12.0"},"_hasShrinkwrap":false,"devDependencies":{"tsx":"^4.19.2","bun-types":"^1.4.2","typescript":"^5","@types/node":"^22"},"_npmOperationalInternal":{"tmp":"tmp/skill-state-mcp-server_1.0.0_1788686367118_0.22029273087436585","host":"s3://npm-registry-packages-npm-production"}},"1.0.1":{"name":"@bub0lehich/skill-state-mcp-server","version":"1.0.1","description":"MCP runtime for the SKILL.state architecture (arXiv:2608.26263) — replaces append-only conversational history with an explicit, mutable execution state (P, Σ, O).","repository":{"type":"git","url":"git+https://github.com/Derzkiyboomchik/skill-state-mcp-server.git"},"homepage":"https://github.com/Derzkiyboomchik/skill-state-mcp-server#readme","bugs":{"url":"https://github.com/Derzkiyboomchik/skill-state-mcp-server/issues"},"keywords":["mcp","model-context-protocol","skill-state","agent","ai-agents","llm","context-optimization","state-machine"],"license":"MIT","type":"module","main":"./dist/index.js","types":"./dist/index.d.ts","bin":{"skill-state-mcp-server":"dist/index.js"},"scripts":{"build":"tsc -p tsconfig.build.json","prepublishOnly":"npm run build","dev":"tsx watch index.ts --http --port 3211","start":"node dist/index.js","start:dev":"tsx index.ts","start:http":"node dist/index.js --http --port 3211","start:bun":"bun index.ts","demo":"tsx demo/demo-client.ts","demo:bun":"bun demo/demo-client.ts","typecheck":"tsc --noEmit","test":"tsx --test tests/*.test.ts"},"dependencies":{"@clack/prompts":"^1.7.0","@modelcontextprotocol/sdk":"^1.12.0","zod":"^3.25.0"},"devDependencies":{"@types/node":"^22","bun-types":"^1.4.2","tsx":"^4.19.2","typescript":"^5"},"gitHead":"bf0f9a1c0da5b9d6632745b20345f373b9b41df4","_id":"@bub0lehich/skill-state-mcp-server@1.0.1","_nodeVersion":"24.14.1","_npmVersion":"11.19.0","dist":{"integrity":"sha512-bYXWBX8JH1BmHe+Ry/1YWyKYALEVIggZyixAPxhVvh7QkRx4JK+QygVS1sKENFVcsOqszyW2UuoqiaRxwD6reg==","shasum":"67a106b0df8da021550fee2683a4743218d1b612","tarball":"https://registry.npmjs.org/@bub0lehich/skill-state-mcp-server/-/skill-state-mcp-server-1.0.1.tgz","fileCount":21,"unpackedSize":1478991,"signatures":[{"keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U","sig":"MEYCIQCSMJKUqVnyMNGYvvmkW4Bvqbe59FJonLR0Fell6394HQIhALOWMe19fPJDDCrdQl2fjdz9HdcUWyz4DXTRveoK79wj"}]},"_npmUser":{"name":"bub0lehich","email":"kapetanamerika77@gmail.com"},"directories":{},"maintainers":[{"name":"bub0lehich","email":"kapetanamerika77@gmail.com"}],"_npmOperationalInternal":{"host":"s3://npm-registry-packages-npm-production","tmp":"tmp/skill-state-mcp-server_1.0.1_1788687184524_0.5174268730724445"},"_hasShrinkwrap":false}},"time":{"created":"2026-09-06T09:19:26.946Z","modified":"2026-09-06T09:33:04.976Z","1.0.0":"2026-09-06T09:19:27.304Z","1.0.1":"2026-09-06T09:33:04.773Z"},"bugs":{"url":"https://github.com/Derzkiyboomchik/skill-state-mcp-server/issues"},"license":"MIT","homepage":"https://github.com/Derzkiyboomchik/skill-state-mcp-server#readme","keywords":["mcp","model-context-protocol","skill-state","agent","ai-agents","llm","context-optimization","state-machine"],"repository":{"type":"git","url":"git+https://github.com/Derzkiyboomchik/skill-state-mcp-server.git"},"description":"MCP runtime for the SKILL.state architecture (arXiv:2608.26263) — replaces append-only conversational history with an explicit, mutable execution state (P, Σ, O).","maintainers":[{"name":"bub0lehich","email":"kapetanamerika77@gmail.com"}],"readme":"

\n \"SKILL.state\n

\n\n

\n \"SKILL.state\n

\n\n

SKILL.state MCP Runtime

\n\n

\n Formal state-based execution runtime for long-horizon AI agents.
\n An official Model Context Protocol implementation of arXiv:2608.26263.\n

\n\n

\n \"npm\n \"arXiv\n \"MCP\n \"Node\n \"License:\n

\n\n---\n\n## Overview\n\nTraditional LLM agent workflows rely on **append-only conversation history** `[m_1, r_1, o_1, m_2, r_2, ...]`. Over long horizons, this design exhibits three fundamental failure modes:\n1. **Context Bloat:** Token consumption scales monotonically as $\\mathcal{O}(T)$, exhausting context windows and elevating per-turn latency.\n2. **Reasoning Poisoning:** Stale thoughts ($R_t$) and abandoned hypotheses persist in context, biassing subsequent turns.\n3. **State Hallucination:** Agents lose track of variables, counters, and completed subtasks buried across thousands of tokens of prose.\n\n**SKILL.state** ([arXiv:2608.26263](https://arxiv.org/html/2608.26263)) replaces conversational history with an explicit, formal state tuple **$(P, \\Sigma_t, O_t)$**:\n- **$P$:** Immutable skill specification (frozen task instructions).\n- **$\\Sigma_t$:** Explicit, typed execution state (JSON object).\n- **$O_t$:** Latest environment observation.\n- **$R_t$:** Chain-of-thought reasoning, **discarded at the tool boundary** each turn to prevent reasoning loops and context leakage.\n\n```\nConventional Agent (Append-Only History)\n[msg1][R1][O1][msg2][R2][O2][msg3]... ──▶ Context grows monotonically ──▶ Poisoning & Rot\n\nSKILL.state (Formal State Runtime)\nTurn t input: (P, Σ_t, O_t)\nLLM response: R_t (discarded) + ΔΣ_t (sparse patch) + a_t (action)\nServer transition: Σ_{t+1} = Σ_t ⊕ ΔΣ_t ──▶ Execute a_t ──▶ O_{t+1}\nTurn t+1 input: (P, Σ_{t+1}, O_{t+1}) [Context size remains O(1) bounded]\n```\n\n---\n\n## Installation & Setup\n\nIn accordance with standard Model Context Protocol deployment patterns, the server can be run dynamically via **`npx`** (recommended for all MCP clients) or installed globally via **`npm`**.\n\n### 1. Claude Desktop\n\nAdd the server to your `claude_desktop_config.json`:\n- **macOS:** `~/Library/Application Support/Claude/claude_desktop_config.json`\n- **Windows:** `%APPDATA%\\Claude\\claude_desktop_config.json`\n\n```json\n{\n \"mcpServers\": {\n \"skill-state\": {\n \"command\": \"npx\",\n \"args\": [\"-y\", \"@bub0lehich/skill-state-mcp-server\"]\n }\n }\n}\n```\n\n### 2. Claude Code (CLI)\n\nRegister the server using Anthropic's Claude Code CLI:\n\n```bash\nclaude mcp add skill-state -- npx -y @bub0lehich/skill-state-mcp-server\n```\n\n### 3. Cursor\n\nAdd to `.cursor/mcp.json` in your project root or open **Settings -> Features -> MCP -> Add New MCP Server**:\n\n```json\n{\n \"mcpServers\": {\n \"skill-state\": {\n \"command\": \"npx\",\n \"args\": [\"-y\", \"@bub0lehich/skill-state-mcp-server\"]\n }\n }\n}\n```\n\n### 4. VS Code (Cline / Roo Code / Continue)\n\nAdd to `cline_mcp_settings.json` or your MCP extension configuration:\n\n```json\n{\n \"mcpServers\": {\n \"skill-state\": {\n \"command\": \"npx\",\n \"args\": [\"-y\", \"@bub0lehich/skill-state-mcp-server\"]\n }\n }\n}\n```\n\n### 5. Persistent Global Installation\n\nIf you prefer installing the binary once onto your system rather than downloading via `npx`:\n\n```bash\nnpm install -g @bub0lehich/skill-state-mcp-server\n```\n\nOnce installed, reference the binary directly:\n\n```json\n{\n \"mcpServers\": {\n \"skill-state\": {\n \"command\": \"skill-state-mcp-server\"\n }\n }\n}\n```\n\n### 6. Programmatic Usage (Node.js SDK)\n\nInstall as a dependency in your application:\n\n```bash\nnpm install @bub0lehich/skill-state-mcp-server\n```\n\n```typescript\nimport { McpServer } from \"@modelcontextprotocol/sdk/server/mcp.js\";\nimport { registerSkillStateTools } from \"@bub0lehich/skill-state-mcp-server\";\n```\n\n---\n\n## Transports & CLI Usage\n\n### stdio Transport (Default)\n\nUsed by Claude Desktop, Cursor, and IDEs via stdin/stdout:\n\n```bash\nnpx -y @bub0lehich/skill-state-mcp-server\n```\n\n### Streamable HTTP Transport (SSE)\n\nFor microservice architectures and remote agents:\n\n```bash\nnpx -y @bub0lehich/skill-state-mcp-server --http --port 3211\n```\n\n- **MCP Endpoint:** `POST http://localhost:3211/mcp`\n- **Liveness Probe:** `GET http://localhost:3211/health`\n\n---\n\n## The $\\oplus$ State Merge Operator\n\nAt each step $t$, the agent emits a sparse state patch $\\Delta\\Sigma_t$. The runtime applies the formal merge operator:\n\n$$\\Sigma_{t+1} = \\Sigma_t \\oplus \\Delta\\Sigma_t$$\n\nNull serves as an explicit **first-class deletion instruction**, distinguishing field removal from field omission:\n\n| Patch Value in $\\Delta\\Sigma_t$ | Semantics on Target State $\\Sigma$ |\n|---|---|\n| `\"key\": null` | **Deletes** the key from $\\Sigma$ |\n| `\"key\": value` | Inserts or overwrites scalar value |\n| `\"key\": { ... }` | Recursively merges nested objects (`null` deletes nested keys) |\n| `\"key\": [ ... ]` | Replaces array wholesale (deterministic, avoids positional diffing) |\n| *(omitted)* | **Preserved** (sparse delta) |\n\n### Example\n\n```jsonc\n// Current State Σ_t\n{\n \"order_id\": \"ORD-402\",\n \"phase\": \"inventory_lookup\",\n \"scratchpad\": \"checking shelf availability...\",\n \"attempts\": 1\n}\n\n// Patch ΔΣ_t // New State Σ_{t+1}\n{ {\n \"phase\": \"packing\", \"order_id\": \"ORD-402\",\n \"scratchpad\": null, ⊕ = \"phase\": \"packing\",\n \"shelf\": \"shelf_42\", \"shelf\": \"shelf_42\",\n \"attempts\": 2 \"attempts\": 2\n} }\n```\n\n---\n\n## MCP Protocol Surface\n\n### Tools\n\n| Tool | Parameters | Description |\n|---|---|---|\n| `initialize_skill` | `skill_specification`, `initial_state`, `state_schema`?, `environment`?, `session_id`? | Boots a new state session and returns the $(P, \\Sigma_0, O_0)$ tuple. |\n| `execute_step` | `session_id`, `reasoning_trace`, `state_update`, `action`, `environment_observation`? | Executes a turn: drops $R_t$, merges $\\Delta\\Sigma_t$, executes $a_t$, and returns $(P, \\Sigma_{t+1}, O_{t+1})$. Rolls back $\\Sigma$ on validation error or action rejection. |\n| `inject_observation` | `session_id`, `observation`, `state_patch`? | Injects external observations or asynchronous environment updates (§5.4 State Recovery). |\n| `parse_turn_response` | `response_text` | Utility to extract $R_t$, $\\Delta\\Sigma_t$, and $a_t$ from raw fenced ```json blocks (Appendix A.4). |\n| `close_session` | `session_id` | Finalizes a session and returns the terminal state snapshot. |\n\n### Resources\n\nInspection endpoints operate with zero LLM-context cost:\n- `skill-state://{session_id}`: Inspect specification $P$, current state $\\Sigma_t$, step counter, and metadata.\n- `skill-state://sessions`: List active sessions and lifecycle metrics.\n\n### Prompts\n\n- `skill_state_turn`: Standard prompt rendering $(P, \\Sigma_t, O_t)$ for tool-calling agents.\n- `skill_state_paper_turn`: Canonical single-line JSON format specified in arXiv:2608.26263 Appendix A.4.\n\n---\n\n## Environments & Benchmarks\n\n### Warehouse Management (`SkillExecBench Environment 1`)\nA reference implementation of the benchmark environment from §4.1:\n- **500 independent shelves** (`shelf_0` through `shelf_499`).\n- **Domain commands:** `Store `, `Ship `, `Move `, `Wait`, `Complete`.\n- **Collision rejection:** Storing onto an occupied shelf triggers an environment rejection and transactionally rolls back state mutations (Appendix B.1).\n- **Background telemetry noise:** Periodic sensor, battery, and robot telemetry injection to evaluate agent resilience against observation drift (Experiment 2).\n\n### Mock Environment\nDeterministic echo, no-op, synthetic failure, and custom completion actions for testing and integration.\n\n---\n\n## Architecture & Guarantees\n\n- **Transactional Rollback:** If candidate state $\\Sigma_{cand} = \\Sigma_t \\oplus \\Delta\\Sigma_t$ fails schema validation or if the executor rejects $a_t$, the runtime rolls back to $\\Sigma_t$ without advancing the turn counter (§3.1, §7).\n- **Zero Leakage:** Reasoning traces $R_t$ are consumed and dropped in memory; they are never logged, hashed, or returned in subsequent MCP turn payloads.\n- **Concurrency Isolation:** Per-session asynchronous mutexes guarantee that concurrent steps within a session are serialized while independent sessions execute concurrently.\n- **Specification Immutability:** $P$ is deep-frozen on initialization to prevent drift across long execution horizons.\n\n---\n\n## Development\n\n```bash\n# Clone repository\ngit clone https://github.com/Derzkiyboomchik/skill-state-mcp-server.git\ncd skill-state-mcp-server\n\n# Install dependencies\nnpm install\n\n# Run 18 unit and integration tests\nnpm test\n\n# Run end-to-end demo client (stdio & HTTP)\nnpm run demo\n\n# Build TypeScript to dist/\nnpm run build\n```\n\n---\n\n## Citation\n\n```bibtex\n@article{skillstate2026,\n title = {SKILL.state: Formal State-Based Execution for Long-Horizon AI Agents},\n journal = {arXiv preprint arXiv:2608.26263},\n year = {2026}\n}\n```\n\n---\n\n## License\n\nMIT © [Derzkiyboomchik](https://github.com/Derzkiyboomchik) & [bub0lehich](https://www.npmjs.com/~bub0lehich)\r\n","readmeFilename":"README.md"}