@hs-x/mcp

The public HS-X MCP server, for developer-side coding agents. It exposes the same safe project substrate the hs-x CLI runs on — status, validation, existing-session inspection, and docs — over a transport-independent JSON-RPC handler (callMcpTool()) plus a stdio entrypoint.

Tools

| Tool | What it does | | --- | --- | | hsx.status | Local project status, via the same substrate as hs-x status | | hsx.check | Runs hs-x check and returns structured diagnostics | | hsx.dev.session.status / .stop | Inspects or safely stops an existing, identity-verified project dev session | | hsx.dev.logs | The merged log surface: tails the dev-session log and, when the project has a deployed app binding, folds in HubSpot app-log rows — the same timeline as hs-x logs | | hsx.secrets.hubspot_oauth.set | Stores a HubSpot app OAuth client secret for one account/project/environment/app after explicit confirm: true | | hsx.docs.search / hsx.docs.fetch | Searches the HS-X docs and fetches a page as clean markdown |

Most tools take a root argument pointing at the local project directory.

Every advertised input schema is closed at the top level (additionalProperties: false). Required values and stable bounds are declared in tools/list and enforced by the dispatcher before a tool performs project, process, filesystem, or network work.

For tools/call, malformed JSON-RPC envelopes and unknown tool names remain JSON-RPC errors. Once a known tool has been selected, invalid arguments and execution failures are returned as MCP tool results with isError: true and a text error payload. Clients should check isError before consuming the text content. Direct callers of callMcpTool() receive the same failures as rejected promises.

Security gates

Project-code execution tools are not advertised by the local MCP server. The former environment-variable opt-in was removed because it executed project code inside the credential-bearing MCP process. Use the CLI directly for local invocation and dev-server startup until HS-X has a separately deployed, credential-isolated sandbox service.

hsx.secrets.hubspot_oauth.set sends credentials only to the exact public HTTPS origin configured by the server's HSX_CONTROL_PLANE_URL (default https://api.hs-x.dev). Tool calls cannot override that destination. Origins with credentials, paths, queries, fragments, loopback, or private IP addresses are rejected. The production HTTPS connection is pinned to an address from that validated DNS result while TLS still verifies the configured hostname; redirects are not followed and responses are bounded to 64 KiB. The call must also include confirm: true; missing or false confirmation is rejected before the server reads its bearer credential, resolves the destination, or starts transport. Credential responses must be valid UTF-8 JSON. Docs responses are also read as bounded streams: 1 MiB for the catalog and 2 MiB for a page, both with fatal UTF-8 decoding so a bad upstream cannot grow the MCP process without bound.

Running it

The stdio entrypoint speaks MCP over stdin/stdout, so any MCP-capable agent can launch it as a subprocess. For embedding, call callMcpTool(name, args) directly against the same dispatcher.

Requests use newline-delimited JSON-RPC and each line is limited to 1 MiB of UTF-8 bytes. The transport reports an invalid-request error as soon as a line crosses that limit, drops its buffered prefix, discards through the next newline, and then continues serving later requests. This keeps an unterminated or multi-byte oversized line from growing the server's input buffer without bound.

Part of HS-X

HS-X is a leaveable, type-safe HubSpot app framework on Cloudflare Workers. Start with the CLI:

npm i -g @hs-x/cli
hs-x init myapp

See @hs-x/cli and the docs at hs-x.dev/docs.

License

Apache-2.0