{"_id":"@cuntinum/khp","_rev":"2-922ed3a37781fe8328233fede02079c6","name":"@cuntinum/khp","dist-tags":{"latest":"0.1.1"},"versions":{"0.1.0":{"name":"@cuntinum/khp","version":"0.1.0","keywords":["hardware","iot","ai","mcp","robotics","lab-automation","protocol"],"author":{"name":"Cuntinum","email":"dev@cuntinum.com"},"license":"Apache-2.0","_id":"@cuntinum/khp@0.1.0","maintainers":[{"name":"truthlocks","email":"nnaaigwiloh@truthlocks.com"}],"homepage":"https://github.com/Cuntinum/model-hardware-protocol#readme","bugs":{"url":"https://github.com/Cuntinum/model-hardware-protocol/issues"},"dist":{"shasum":"495101cad118975b365f1a72de5b4042222b02cd","tarball":"https://registry.npmjs.org/@cuntinum/khp/-/khp-0.1.0.tgz","fileCount":47,"integrity":"sha512-kleHaiyARYtunmOR0Any+Cm5+Q3n+ZoYMBhAfyuVUhqUFyE2M3ImoEwOoNW8wfgsXGO0h1Mnxno3/5LBCuF55w==","signatures":[{"sig":"MEUCIDrzlbwPXtxxpLlS8Wbu3KVXUbMQItxUOlAs7D1420U9AiEAp5OS9yQ36o7pp/5+zwFq7NU7764uGcvfqPIuYwWHZ2w=","keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U"}],"unpackedSize":138536},"main":"dist/index.js","type":"module","types":"dist/index.d.ts","engines":{"node":">=18"},"gitHead":"26f7b999540f97140c85a299b5c7c23c2a073d55","scripts":{"dev":"tsc --watch","lint":"eslint src/","test":"vitest","build":"tsc","clean":"rm -rf dist/"},"_npmUser":{"name":"truthlocks","email":"nnaaigwiloh@truthlocks.com"},"repository":{"url":"git+https://github.com/Cuntinum/model-hardware-protocol.git","type":"git"},"_npmVersion":"11.17.0","description":"Model Hardware Protocol — TypeScript SDK for AI agents controlling physical devices","directories":{},"_nodeVersion":"24.19.0","dependencies":{},"_hasShrinkwrap":false,"devDependencies":{"eslint":"^9","vitest":"^2.0","typescript":"^5.5","@types/node":"^22"},"peerDependencies":{"@modelcontextprotocol/sdk":">=0.5"},"peerDependenciesMeta":{"@modelcontextprotocol/sdk":{"optional":true}},"_npmOperationalInternal":{"tmp":"tmp/khp_0.1.0_1787941512868_0.3480185142687622","host":"s3://npm-registry-packages-npm-production"}},"0.1.1":{"name":"@cuntinum/khp","version":"0.1.1","description":"Model Hardware Protocol: TypeScript SDK for AI agents controlling physical devices","type":"module","main":"dist/index.js","types":"dist/index.d.ts","scripts":{"build":"tsc","dev":"tsc --watch","test":"vitest","lint":"eslint src/","clean":"rm -rf dist/"},"keywords":["hardware","iot","ai","mcp","robotics","lab automation","protocol","model hardware protocol"],"author":{"name":"Cuntinum","email":"dev@cuntinum.com"},"license":"Apache-2.0","repository":{"type":"git","url":"git+https://github.com/Cuntinum/model-hardware-protocol.git"},"engines":{"node":">=18"},"dependencies":{},"devDependencies":{"typescript":"^5.5","vitest":"^2.0","@types/node":"^22","eslint":"^9"},"peerDependencies":{"@modelcontextprotocol/sdk":">=0.5"},"peerDependenciesMeta":{"@modelcontextprotocol/sdk":{"optional":true}},"gitHead":"f1bbbece1f5c4a3953051f9a30a294b86559515e","_id":"@cuntinum/khp@0.1.1","bugs":{"url":"https://github.com/Cuntinum/model-hardware-protocol/issues"},"homepage":"https://github.com/Cuntinum/model-hardware-protocol#readme","_nodeVersion":"24.19.0","_npmVersion":"11.17.0","dist":{"integrity":"sha512-kLuQGJM0fDH3aB1zYDWXZxZtBeEHxdcLRUHZ4Ii+MOhjNrvvnWaOraF4shxVlNri+8n8wATq8e9cFSOZ3ocwdA==","shasum":"e0f1e9069714f26fe27a427220f48332a40cf591","tarball":"https://registry.npmjs.org/@cuntinum/khp/-/khp-0.1.1.tgz","fileCount":48,"unpackedSize":147016,"signatures":[{"keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U","sig":"MEUCID5TK/+KUKZAUuI/fJ7QRjvoB5wBAFCmUmkzz/5VFOAFAiEAkUr62wXdU4K7N3LrVT5VLIVE1eIMib2E0TwCFM0wPyY="}]},"_npmUser":{"name":"truthlocks","email":"nnaaigwiloh@truthlocks.com"},"directories":{},"maintainers":[{"name":"truthlocks","email":"nnaaigwiloh@truthlocks.com"}],"_npmOperationalInternal":{"host":"s3://npm-registry-packages-npm-production","tmp":"tmp/khp_0.1.1_1787941860977_0.6425718897002393"},"_hasShrinkwrap":false}},"time":{"created":"2026-08-28T18:25:12.686Z","modified":"2026-08-28T18:31:01.300Z","0.1.0":"2026-08-28T18:25:13.041Z","0.1.1":"2026-08-28T18:31:01.122Z"},"bugs":{"url":"https://github.com/Cuntinum/model-hardware-protocol/issues"},"author":{"name":"Cuntinum","email":"dev@cuntinum.com"},"license":"Apache-2.0","homepage":"https://github.com/Cuntinum/model-hardware-protocol#readme","keywords":["hardware","iot","ai","mcp","robotics","lab automation","protocol","model hardware protocol"],"repository":{"type":"git","url":"git+https://github.com/Cuntinum/model-hardware-protocol.git"},"description":"Model Hardware Protocol: TypeScript SDK for AI agents controlling physical devices","maintainers":[{"name":"truthlocks","email":"nnaaigwiloh@truthlocks.com"}],"readme":"<p align=\"center\">\n  <h1 align=\"center\">@cuntinum/khp</h1>\n  <p align=\"center\">\n    <strong>Model Hardware Protocol: TypeScript SDK for AI agents controlling physical devices.</strong>\n  </p>\n  <p align=\"center\">\n    <a href=\"https://www.npmjs.com/package/@cuntinum/khp\"><img src=\"https://img.shields.io/npm/v/@cuntinum/khp?style=flat-square\" alt=\"npm version\"></a>\n    <a href=\"https://github.com/Cuntinum/model-hardware-protocol\"><img src=\"https://img.shields.io/github/stars/Cuntinum/model-hardware-protocol?style=flat-square\" alt=\"GitHub stars\"></a>\n    <a href=\"https://github.com/Cuntinum/model-hardware-protocol/blob/main/LICENSE\"><img src=\"https://img.shields.io/badge/license-Apache%202.0-blue?style=flat-square\" alt=\"License\"></a>\n  </p>\n</p>\n\n<br>\n\n## What is MHP?\n\n**Model Hardware Protocol** is a production grade, open source specification that lets any AI model (Claude, GPT, Gemini, Llama, or your own) discover, communicate with, and orchestrate physical hardware through a universal driver interface.\n\nThis package is the official TypeScript SDK. It provides everything you need to build hardware drivers, run an MCP server, and coordinate devices through the State Bus.\n\n<br>\n\n## Installation\n\n```bash\nnpm install @cuntinum/khp\n```\n\n<br>\n\n## Core Modules\n\n| Module | Purpose |\n|--------|---------|\n| `Driver` | Abstract base class for all hardware drivers |\n| `StateBus` | Shared memory with typed slots, transforms, and pub/sub events |\n| `DeviceRegistry` | File based device discovery and registration |\n| `Manifest` | Capabilities validation and export |\n| `KHPMCPServer` | Full Model Context Protocol server (8 tools) |\n| `Errors` | Typed error hierarchy with protocol error codes |\n| `Decorators` | `@readable`, `@writable`, `@procedure`, `@safety`, `@monitor` |\n\n<br>\n\n## Quick Start: Write a Driver\n\n```typescript\nimport { Driver, readable, writable, procedure, safety, ConnectionType } from '@cuntinum/khp';\n\nclass TemperatureSensor extends Driver {\n  name = 'Lab Thermocouple';\n  deviceType = 'sensor';\n  version = '1.0.0';\n  connectionType = ConnectionType.SERIAL;\n\n  private _currentTemp = 22.5;\n  private _threshold = 80.0;\n\n  constructor() {\n    super('sensor_001');\n\n    // Register readable properties\n    this._readableProps.set('temperature', {\n      type: 'float',\n      description: 'Current temperature',\n      unit: 'celsius',\n      minValue: -40,\n      maxValue: 200,\n    });\n\n    // Register writable properties with safety\n    this._writableProps.set('alert_threshold', {\n      type: 'float',\n      description: 'Alert threshold',\n      unit: 'celsius',\n    });\n\n    // Register hard safety limit\n    this._safetyLimits.push({\n      propertyName: 'alert_threshold',\n      max: 200.0,\n      min: -40.0,\n      reason: 'Sensor rated from negative 40 to 200 celsius',\n      hard: true,\n    });\n  }\n\n  temperature(): number {\n    return this._currentTemp;\n  }\n\n  set_alert_threshold(value: number): void {\n    this._threshold = value;\n  }\n}\n```\n\n<br>\n\n## MCP Server (AI Agent Integration)\n\nExpose your hardware to any MCP compatible AI agent:\n\n```typescript\nimport { KHPMCPServer } from '@cuntinum/khp';\n\nconst server = new KHPMCPServer();\nserver.registerDriver(new TemperatureSensor());\nserver.serve(7400);\n```\n\nThis exposes 8 MCP tools:\n\n| Tool | Description |\n|------|-------------|\n| `khp_discover` | Find available devices |\n| `khp_read` | Read a device property |\n| `khp_write` | Write a property (safety enforced) |\n| `khp_execute` | Run a procedure |\n| `khp_manifest` | Get full device capabilities |\n| `khp_bus_read` | Read from shared State Bus |\n| `khp_bus_write` | Write to shared State Bus |\n| `khp_emergency_stop` | Emergency halt |\n\n<br>\n\n## State Bus (Multi Device Coordination)\n\n```typescript\nimport { StateBus, Transform } from '@cuntinum/khp';\n\nconst bus = new StateBus();\n\n// Create typed data channels\nbus.createSlot('reactor_temp', { type: 'float', unit: 'celsius' });\n\n// Automatic transforms\nbus.addTransform(new Transform({\n  transformId: 'overheat',\n  inputSlot: 'reactor_temp',\n  operation: 'threshold',\n  params: { above: 95.0 },\n  outputEvent: 'overheat_alarm',\n}));\n\n// React to events\nbus.on('overheat_alarm', (event) => {\n  console.log('ALERT: Temperature exceeded threshold!');\n});\n\n// Devices write, agents read\nbus.writeSlot('reactor_temp', 97.5);\n// >>> fires overheat_alarm event\n```\n\n<br>\n\n## Device Discovery\n\n```typescript\nimport { DeviceRegistry } from '@cuntinum/khp';\n\nconst registry = new DeviceRegistry({ configDir: './devices' });\n\n// Register devices\nregistry.register(new TemperatureSensor());\n\n// Discover by type\nconst sensors = registry.listDevices({ deviceType: 'sensor' });\n```\n\n<br>\n\n## Safety Model\n\nMHP enforces three layers of safety that the AI agent cannot bypass:\n\n| Layer | Behavior | Example |\n|-------|----------|---------|\n| **Hard Limits** | Operation refused entirely | Write 300 celsius to a sensor rated to 200 → `SafetyBlockedError` |\n| **Soft Limits** | Value silently clamped | Write 100 to a max 80 → actual value set to 80 |\n| **Confirmation Gates** | Requires human approval | Dangerous procedure → `ConfirmationRequiredError` with approval ID |\n\nEmergency stop is universal: `driver.emergencyStop()` immediately halts all operations.\n\n<br>\n\n## Error Types\n\n```typescript\nimport {\n  KHPError,\n  SafetyBlockedError,\n  ConfirmationRequiredError,\n  PreconditionFailedError,\n  PropertyNotFoundError,\n  DeviceOfflineError,\n  ConnectionFailedError,\n  TimeoutError,\n  ManifestValidationError,\n  DriverLoadError,\n} from '@cuntinum/khp';\n```\n\nAll errors include `deviceId`, `code`, and `toJSON()` for serialization.\n\n<br>\n\n## Manifest Generation\n\nEvery driver auto generates a JSON manifest describing its full capabilities:\n\n```typescript\nconst sensor = new TemperatureSensor();\nconst manifest = sensor.getManifest();\n\nconsole.log(manifest);\n// {\n//   \"$schema\": \"https://khp.dev/schema/manifest/v1\",\n//   \"device_id\": \"sensor_001\",\n//   \"name\": \"Lab Thermocouple\",\n//   \"type\": \"sensor\",\n//   \"readable\": { \"temperature\": { type: \"float\", unit: \"celsius\" } },\n//   \"writable\": { \"alert_threshold\": { type: \"float\", unit: \"celsius\" } },\n//   \"safety\": { \"hard_limits\": { ... } },\n//   ...\n// }\n```\n\n<br>\n\n## Full API Reference\n\n### Driver Base Class\n\n| Method | Description |\n|--------|-------------|\n| `connect()` | Establish connection to hardware |\n| `disconnect()` | Close connection gracefully |\n| `read(property)` | Read a property value |\n| `write(property, value)` | Write a value (safety enforced) |\n| `execute(procedure, params)` | Run a named procedure |\n| `emergencyStop()` | Immediately halt all operations |\n| `getManifest()` | Export capabilities as JSON |\n| `healthCheck()` | Test connection status |\n| `onEvent(type, handler)` | Subscribe to device events |\n| `setTags(tags)` | Add metadata tags |\n\n### StateBus\n\n| Method | Description |\n|--------|-------------|\n| `createSlot(name, options)` | Create a typed data channel |\n| `writeSlot(name, value)` | Update a slot value |\n| `readSlot(name)` | Read current slot value |\n| `addTransform(transform)` | Add automatic data transform |\n| `on(event, handler)` | Subscribe to bus events |\n\n### DeviceRegistry\n\n| Method | Description |\n|--------|-------------|\n| `register(driver)` | Register a device |\n| `deregister(deviceId)` | Remove a device |\n| `listDevices(filter?)` | List registered devices |\n| `getDevice(deviceId)` | Get a specific device |\n\n<br>\n\n## Requirements\n\n- Node.js 18 or higher\n- TypeScript 5.5+ (for decorators)\n- Optional: `@modelcontextprotocol/sdk` for MCP server functionality\n\n<br>\n\n## Python SDK\n\nThe Python equivalent is available on PyPI:\n\n```bash\npip install khp\n```\n\nBoth SDKs share identical APIs and full interoperability through the MHP protocol.\n\n<br>\n\n## Links\n\n- [GitHub Repository](https://github.com/Cuntinum/model-hardware-protocol)\n- [Full Documentation](https://github.com/Cuntinum/model-hardware-protocol/tree/main/docs)\n- [Protocol Specification](https://github.com/Cuntinum/model-hardware-protocol/tree/main/spec)\n- [10 Reference Drivers](https://github.com/Cuntinum/model-hardware-protocol/tree/main/drivers)\n- [Contributing Guide](https://github.com/Cuntinum/model-hardware-protocol/blob/main/CONTRIBUTING.md)\n\n<br>\n\n## License\n\nApache 2.0: Use commercially. Fork freely. Contribute back.\n\n<br>\n\n<p align=\"center\">\n  <strong>Built by <a href=\"https://cuntinum.com\">Cuntinum</a></strong><br>\n  Making AI work in the physical world.\n</p>\n","readmeFilename":"README.md"}