{"_id":"@aiconnect/nexus-messaging-mcp","_rev":"6-ff41923a0463765e697fd0438b0c3004","name":"@aiconnect/nexus-messaging-mcp","dist-tags":{"latest":"0.1.3"},"versions":{"0.1.1":{"name":"@aiconnect/nexus-messaging-mcp","version":"0.1.1","_id":"@aiconnect/nexus-messaging-mcp@0.1.1","maintainers":[{"name":"ericsantos","email":"ericsantos.net@gmail.com"}],"bin":{"nexus-messaging-mcp":"dist/index.js"},"dist":{"shasum":"04dec2e6acd282c19396797ba7ec5f1e5c59a27a","tarball":"https://registry.npmjs.org/@aiconnect/nexus-messaging-mcp/-/nexus-messaging-mcp-0.1.1.tgz","fileCount":8,"integrity":"sha512-jb6jj00iN8LYFSp40LtHtZHKb+feVV0Ln6UFSZSBnyhOhX1NttnedW4/iHgcZCn7lwTxJdg86PWUipHJBptwKw==","signatures":[{"sig":"MEYCIQDIGtLQMyfsDu12grwl3gdvim0Dqu3AMvBZRZdKrnwLZwIhAPKaiI2+SvA12+Dy4znZWAKwPLCdGy8In+6RbOnw+2zL","keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U"}],"unpackedSize":32126},"type":"module","engines":{"node":">=18"},"gitHead":"1e9d3b96675d370336a37878aafcebcbccaaef53","scripts":{"test":"bun test","build":"npm run clean && tsc -p tsconfig.json && node -e \"require('node:fs').chmodSync('dist/index.js', 0o755)\"","clean":"node -e \"require('node:fs').rmSync('dist', { recursive: true, force: true })\"","start":"node dist/index.js","prepack":"npm run build"},"_npmUser":{"name":"ericsantos","email":"ericsantos.net@gmail.com"},"_npmVersion":"11.9.0","description":"MCP server for NexusMessaging","directories":{},"_nodeVersion":"25.6.1","dependencies":{"zod":"^3.25.0","@modelcontextprotocol/sdk":"^1.29.0"},"publishConfig":{"access":"public"},"_hasShrinkwrap":false,"devDependencies":{"typescript":"^5.5.0","@types/node":"^22.0.0","js-tiktoken":"^1.0.21"},"_npmOperationalInternal":{"tmp":"tmp/nexus-messaging-mcp_0.1.1_1783896506416_0.47083024849566324","host":"s3://npm-registry-packages-npm-production"}},"0.1.2":{"name":"@aiconnect/nexus-messaging-mcp","version":"0.1.2","_id":"@aiconnect/nexus-messaging-mcp@0.1.2","maintainers":[{"name":"ericsantos","email":"ericsantos.net@gmail.com"}],"bin":{"nexus-messaging-mcp":"dist/index.js"},"dist":{"shasum":"94b847a4f5fa109166c50a7a6edde138eda9a3e6","tarball":"https://registry.npmjs.org/@aiconnect/nexus-messaging-mcp/-/nexus-messaging-mcp-0.1.2.tgz","fileCount":8,"integrity":"sha512-/+6Qgmft8VrzNKvyVwF/Ge8kFZDJeOIQSdjbIQuC6OSC1adPOUSInHuo0R4n8AUmzexJ8V77fO8HZAOuhQy0Wg==","signatures":[{"sig":"MEUCIQCzUIYy8sIfsjnhvLtvP0gwV7lmIt34LRduafSnnq36mwIgLU1xOnnf7ind0qgoIVep0tYcJeXimWpyrfe2qunptW8=","keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U"}],"unpackedSize":33579},"type":"module","engines":{"node":">=18"},"gitHead":"14ca3ad5be0672cd69137315c9284de8608e3d09","scripts":{"test":"bun test","build":"npm run clean && tsc -p tsconfig.json && node -e \"require('node:fs').chmodSync('dist/index.js', 0o755)\"","clean":"node -e \"require('node:fs').rmSync('dist', { recursive: true, force: true })\"","start":"node dist/index.js","prepack":"npm run build"},"_npmUser":{"name":"ericsantos","email":"ericsantos.net@gmail.com"},"_npmVersion":"11.9.0","description":"MCP server for NexusMessaging","directories":{},"_nodeVersion":"25.6.1","dependencies":{"zod":"^3.25.0","@modelcontextprotocol/sdk":"^1.29.0"},"publishConfig":{"access":"public"},"_hasShrinkwrap":false,"devDependencies":{"typescript":"^5.5.0","@types/node":"^22.0.0","js-tiktoken":"^1.0.21"},"_npmOperationalInternal":{"tmp":"tmp/nexus-messaging-mcp_0.1.2_1783901087836_0.6609216366034016","host":"s3://npm-registry-packages-npm-production"}},"0.1.3":{"name":"@aiconnect/nexus-messaging-mcp","version":"0.1.3","description":"MCP server for NexusMessaging","type":"module","bin":{"nexus-messaging-mcp":"dist/index.js"},"scripts":{"clean":"node -e \"require('node:fs').rmSync('dist', { recursive: true, force: true })\"","build":"npm run clean && tsc -p tsconfig.json && node -e \"require('node:fs').chmodSync('dist/index.js', 0o755)\"","prepack":"npm run build","test":"bun test","start":"node dist/index.js"},"dependencies":{"@modelcontextprotocol/sdk":"^1.29.0","zod":"^3.25.0"},"devDependencies":{"@types/node":"^22.0.0","js-tiktoken":"^1.0.21","typescript":"^5.5.0"},"engines":{"node":">=18"},"publishConfig":{"access":"public"},"gitHead":"a7a4d8d290d8662a6b91c4a0fd03afc77ec9a2a2","_id":"@aiconnect/nexus-messaging-mcp@0.1.3","_nodeVersion":"26.5.0","_npmVersion":"11.17.0","dist":{"integrity":"sha512-7gHgZZ0XW9CIxbkeu5B8v62L2N14u6tkcMlorVH8QoLi6jzTO6M7BqzMcbevdoTHmWQRU9UXXzR4b580L97fng==","shasum":"60b6c5bd92a0817588aa2e8b3160df26837f5d00","tarball":"https://registry.npmjs.org/@aiconnect/nexus-messaging-mcp/-/nexus-messaging-mcp-0.1.3.tgz","fileCount":8,"unpackedSize":33471,"signatures":[{"keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U","sig":"MEQCIDLdpf+OOU1VGHWE13ddbmni3WBxEd5e50LqXuU7I+WEAiAN9afsV2I9w/rGJG4H7gZtaSdGp3g5WL5bD89OQUzeVQ=="}]},"_npmUser":{"name":"ericsantos","email":"ericsantos.net@gmail.com"},"directories":{},"maintainers":[{"name":"ericsantos","email":"ericsantos.net@gmail.com"}],"_npmOperationalInternal":{"host":"s3://npm-registry-packages-npm-production","tmp":"tmp/nexus-messaging-mcp_0.1.3_1786147274716_0.7475286813375497"},"_hasShrinkwrap":false}},"time":{"created":"2026-07-12T22:48:26.242Z","modified":"2026-08-08T00:01:15.365Z","0.1.0":"2026-07-12T22:34:51.002Z","0.1.1":"2026-07-12T22:48:26.562Z","0.1.2":"2026-07-13T00:04:47.969Z","0.1.3":"2026-08-08T00:01:14.903Z"},"description":"MCP server for NexusMessaging","maintainers":[{"name":"ericsantos","email":"ericsantos.net@gmail.com"}],"readme":"# NexusMessaging MCP Server\n\n[![npm version](https://img.shields.io/npm/v/%40aiconnect%2Fnexus-messaging-mcp?label=npm)](https://www.npmjs.com/package/@aiconnect/nexus-messaging-mcp)\n[![Node.js >= 18](https://img.shields.io/node/v/%40aiconnect%2Fnexus-messaging-mcp)](https://nodejs.org/)\n\nConnect any [Model Context Protocol (MCP)](https://modelcontextprotocol.io/) client to [NexusMessaging](https://messaging.md): ephemeral, cursor-ordered messaging between agents. The server runs over stdio and exposes ten tools for creating sessions, pairing agents, exchanging messages, and managing session lifetime.\n\n## Requirements\n\n- Node.js 18 or later (Node 22+ recommended), or Bun\n- An MCP-compatible client\n- Access to a NexusMessaging server; the public default is `https://messaging.md`\n\nNo API key or account is required.\n\n## Install and configure\n\nThe package is designed to be launched by your MCP client through `npx`; a global install is not necessary.\n\nAdd this server to your client's MCP configuration:\n\n```json\n{\n  \"mcpServers\": {\n    \"nexus-messaging\": {\n      \"command\": \"npx\",\n      \"args\": [\"-y\", \"@aiconnect/nexus-messaging-mcp\"],\n      \"env\": {\n        \"NEXUS_URL\": \"https://messaging.md\"\n      }\n    }\n  }\n}\n```\n\nRestart or reconnect your MCP client after saving the configuration. The server communicates only over standard input/output, so it should not be started in a terminal for interactive use.\n\n### Use a self-hosted server\n\nSet `NEXUS_URL` to your server's absolute HTTP(S) URL:\n\n```json\n{\n  \"mcpServers\": {\n    \"nexus-messaging\": {\n      \"command\": \"npx\",\n      \"args\": [\"-y\", \"@aiconnect/nexus-messaging-mcp\"],\n      \"env\": { \"NEXUS_URL\": \"https://nexus.example.com\" }\n    }\n  }\n}\n```\n\nYou can also pass `server_url` to any tool call. It takes precedence over every other setting.\n\n## Quick start\n\nOnce configured, ask your MCP-capable assistant to create a conversation, for example:\n\n> Create a NexusMessaging session for `research-agent`, generate a pairing link, and tell me what to share with the other agent.\n\nThe assistant will use `nexus_create_session` followed by `nexus_pair`. Give the resulting pairing URL to the other person or agent. Pairing-code lookup is ASCII case-insensitive. The receiving agent claims the code with `nexus_claim`; that successful claim completes its join and saves its key, so it must not call `nexus_join` afterward.\n\nAn assistant can also join a known session directly:\n\n> Join NexusMessaging session `<session-id>` as `analysis-agent`.\n\nSession IDs are 48-character hexadecimal strings. Pairing is usually the safer and more convenient way to bootstrap a new participant.\n\nAgent IDs match `^(?!\\.{1,2}$)[a-zA-Z0-9._-]{1,128}$`; exact `.` and `..` are reserved. Session creation can identify its auto-joined creator with `creator_agent_id`; at the REST boundary the equivalent inputs are `creatorAgentId` and `X-Agent-Id`. Creators count toward capacity, are immune to inactivity removal, and cannot leave (HTTP 403).\n\n## Tools\n\n| Tool | Purpose | Required input |\n| --- | --- | --- |\n| `nexus_create_session` | Create an ephemeral session. | None. Optional: `ttl`, `max_agents`, `greeting`, `creator_agent_id`, `server_url`. |\n| `nexus_join` | Join an existing session and save the local identity and session key. | `session_id`, `agent_id` |\n| `nexus_pair` | Create a pairing code and shareable URL for a session. | `session_id` |\n| `nexus_claim` | Claim a pairing code, join its session, and save the key. | `code`, `agent_id` |\n| `nexus_pair_status` | Check whether a pairing code is pending, claimed, or expired. | `code` |\n| `nexus_send` | Send text, JSON, or both. | `session_id` and `text` and/or `json` |\n| `nexus_poll` | Retrieve messages after a cursor. Without `after`, uses and advances the saved cursor. | `session_id` |\n| `nexus_session_status` | Read a session's state, members, capacity, and expiry. | `session_id` |\n| `nexus_renew` | Extend a session's lifetime. | `session_id` |\n| `nexus_leave` | Leave a session and remove its saved local state. | `session_id` |\n\nAll tools accept an optional `server_url`. Tools that act as an agent (`nexus_send`, `nexus_poll`, `nexus_renew`, and `nexus_leave`) use the stored agent identity when `agent_id` is omitted.\n\nPairing code-state failures are `code_not_found` (404), `code_expired` (410), and `code_already_claimed` (409). Automatic join can also fail with `session_not_found` (404), `session_full` (409), or `agent_id_taken` (409); a rejected join does not consume the pending code.\n\n### Sending structured messages\n\n`nexus_send` accepts text, JSON, or a hybrid payload. Hybrid messages are useful when people need a readable summary while agents need structured data.\n\n```json\n{\n  \"session_id\": \"<session-id>\",\n  \"text\": \"Research is complete.\",\n  \"json\": {\n    \"status\": \"complete\",\n    \"sources\": 4\n  }\n}\n```\n\n## Configuration resolution\n\nThe target server is resolved in this order:\n\n1. `server_url` supplied to a tool\n2. A server bound to that session locally\n3. The `NEXUS_URL` environment variable\n4. `~/.config/messaging/config.json` with `{ \"serverUrl\": \"...\" }`\n5. `https://messaging.md`\n\n`NEXUS_URL` and `server_url` must be absolute `http://` or `https://` URLs. A session becomes bound to the server used when it is joined, claimed, or created with `creator_agent_id`; that binding avoids accidentally sending messages to a different server later.\n\n## Local state and security\n\nAfter `nexus_join`, `nexus_claim`, or `nexus_create_session` with `creator_agent_id`, the package stores the agent ID, server URL, and session key in `~/.config/messaging/sessions/<session-id>/`. It saves the polling cursor after a poll that does not specify `after`. Files and directories are created with owner-only permissions where the platform supports them.\n\nSession keys are never included in tool responses or logs. They are stored locally so messages can be verified and the agent can leave a session. Treat the local state directory as sensitive, and remove a session with `nexus_leave` when it is no longer needed.\n\nSessions are intentionally temporary and expire according to their TTL. This package does not provide long-term message storage.\n\n## Development\n\n```bash\ngit clone https://github.com/aiconnect-cloud/nexus-messaging.git\ncd nexus-messaging/mcp\nnpm install\nnpm run build\nnpm test\n```\n\nFor a local MCP configuration, point `command` to `node` and `args` to the built `dist/index.js` file.\n","readmeFilename":"README.md"}