pyxis-mcp 0.0.0 → 0.2.0

package/LICENSE

@@ -1,21 +1,21 @@
-MIT License
-
-Copyright (c) 2026 Samuel Santana
-
-Permission is hereby granted, free of charge, to any person obtaining a copy
-of this software and associated documentation files (the "Software"), to deal
-in the Software without restriction, including without limitation the rights
-to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
-copies of the Software, and to permit persons to whom the Software is
-furnished to do so, subject to the following conditions:
-
-The above copyright notice and this permission notice shall be included in all
-copies or substantial portions of the Software.
-
-THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
-IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
-FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
-AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
-LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
-OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
-SOFTWARE.
+MIT License
+
+Copyright (c) 2026 Samuel Santana
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -1,7 +1,262 @@
-# pyxis-mcp
+<div align="center">
 
-The MCP server of [Pyxis](https://pyxis-analytics.dev), privacy-first product analytics: it lets an
-AI agent read your dashboard's numbers with a read-only token you can revoke at any time.
+<picture>
+  <source media="(prefers-color-scheme: dark)" srcset="https://raw.githubusercontent.com/samuelcsantana/pyxis-mcp/main/.github/assets/cover-dark.png">
+  <img alt="Pyxis — privacy-first product analytics" src="https://raw.githubusercontent.com/samuelcsantana/pyxis-mcp/main/.github/assets/cover-light.png" width="100%">
+</picture>
 
-This version only reserves the name. The first usable release is 0.1.0, published from GitHub
-Actions with npm provenance. Source and setup: https://github.com/samuelcsantana/pyxis-mcp
+**The MCP server of Pyxis: lets an AI agent read your dashboard's numbers, with a read-only token
+you can revoke at any time.**
+
+[![CI](https://github.com/samuelcsantana/pyxis-mcp/actions/workflows/ci.yml/badge.svg?branch=main)](https://github.com/samuelcsantana/pyxis-mcp/actions/workflows/ci.yml)
+[![Coverage](https://codecov.io/gh/samuelcsantana/pyxis-mcp/graph/badge.svg)](https://codecov.io/gh/samuelcsantana/pyxis-mcp)
+[![CodeQL](https://github.com/samuelcsantana/pyxis-mcp/actions/workflows/codeql.yml/badge.svg?branch=main)](https://github.com/samuelcsantana/pyxis-mcp/actions/workflows/codeql.yml)
+<br>
+[![License: MIT](https://img.shields.io/github/license/samuelcsantana/pyxis-mcp)](LICENSE)
+[![TypeScript strict](https://img.shields.io/badge/TypeScript-strict-3178C6?logo=typescript&logoColor=white)](tsconfig.json)
+[![Conventional Commits](https://img.shields.io/badge/Conventional%20Commits-1.0.0-FE5196?logo=conventionalcommits&logoColor=white)](https://www.conventionalcommits.org)
+[![npm](https://img.shields.io/npm/v/pyxis-mcp?logo=npm)](https://www.npmjs.com/package/pyxis-mcp)
+[![npm provenance](https://img.shields.io/badge/npm-provenance-2E7D32?logo=npm)](https://www.npmjs.com/package/pyxis-mcp#provenance)
+
+**[Pyxis](https://pyxis-analytics.dev)** · **[Live demo](https://demo.pyxis-analytics.dev)** ·
+**[API reference](https://samuelcsantana.github.io/pyxis-api/)**
+
+</div>
+
+> **Status:** on npm as `pyxis-mcp`, every release published from GitHub Actions with
+> provenance. The fifteen tools read the live Pyxis API. The package also exports them as a
+> library, which a host serves over HTTP with each caller's token.
+
+## Ecosystem
+
+| Repository                                               | Role                                                          |
+| -------------------------------------------------------- | ------------------------------------------------------------- |
+| [pyxis-api](https://github.com/samuelcsantana/pyxis-api) | Ingestion, dashboard sign-in and queries, erasure, retention  |
+| [pyxis-sdk](https://github.com/samuelcsantana/pyxis-sdk) | Browser tracker published to npm as `pyxis-analytics`         |
+| [pyxis-web](https://github.com/samuelcsantana/pyxis-web) | The dashboard: overview, funnels, features, requests          |
+| **pyxis-mcp** (this one)                                 | MCP server that lets an AI agent read the dashboard's numbers |
+
+## Why it exists
+
+More and more questions about a product are asked to an agent instead of a dashboard: "how did
+last week compare", "where does the sign-up funnel lose people", "which route started failing".
+This server gives Claude Code, Claude Desktop, Cursor and other MCP clients the same numbers the
+Pyxis dashboard shows, and nothing more: it uses an access token that only reads, created by an
+admin in the dashboard's Settings and revocable there at any moment. Like the rest of Pyxis, there
+is no personal data to hand over: events carry no cookies, no addresses and no user agents.
+
+## Tools
+
+Every tool only reads, and maps to one `GET` route of the Pyxis API. Dates are `YYYY-MM-DD` in the
+project's time zone; `list_projects` gives each project's today, so call it first.
+
+| Tool               | What it answers                                                                                           |
+| ------------------ | --------------------------------------------------------------------------------------------------------- |
+| `list_projects`    | The projects the token can read: id, name, time zone, today there, conversion event, first and last event |
+| `overview`         | Visits, identified users, conversions and failed writes against the previous period; top pages and events |
+| `devices`          | Visits and conversions by device type, browser, system, country and region                                |
+| `acquisition`      | Visits per day and channel, and the sources and campaigns behind them                                     |
+| `engagement`       | Entry and exit pages, single-page visits, visit length                                                    |
+| `time_of_day`      | Visits by weekday and local hour                                                                          |
+| `features`         | The most used named events or screens, day by day                                                         |
+| `event_properties` | How the property values of one named event break down                                                     |
+| `requests`         | Calls to the site's backend per route: failures, statuses, durations, latest errors                       |
+| `funnel`           | How many visits or people reached each step, and the time between steps                                   |
+| `funnel_segments`  | The same funnel per device type or channel                                                                |
+| `funnel_subjects`  | The visits or people who reached, or dropped at, one step                                                 |
+| `visits`           | The visits of a range, filtered by pages, events, channel, device, country, campaign, failed requests     |
+| `visit_timeline`   | Every event of one visit, or every visit of one identified person                                         |
+| `project_settings` | Time zone, conversion event, allowed origins, retention, live public keys                                 |
+
+A result is JSON text, `{ "untrusted_visitor_text": "…", "report": … }`: the report is the API's
+answer, and the first field reminds the agent that names, paths and values inside it were written by
+the site's visitors. Problems come back as tool errors the agent can act on (a revoked token, an
+unknown project, the rate limit and when to retry). When the API refuses a request (any `4xx`), the
+error carries the API's own code and reason, such as a suspended account; only a `5xx` asks to try
+again later.
+
+## Configuration
+
+| Variable        | Required | Meaning                                                                                                           |
+| --------------- | -------- | ----------------------------------------------------------------------------------------------------------------- |
+| `PYXIS_TOKEN`   | yes      | A read-only access token (`pyxis_at_` and 32 letters and digits), created in the dashboard under Settings         |
+| `PYXIS_API_URL` | no       | The Pyxis API to read, as an origin. Defaults to `https://api.pyxis-analytics.dev`; plain http only for localhost |
+
+A missing or malformed value stops the server with a sentence on standard error that names the
+variable and never repeats its value.
+
+## Use it
+
+Create a token in the dashboard (Settings, Access tokens), then add the server to your client. It
+runs with `npx`, so there is nothing to install beforehand (Node 22 or later).
+
+Claude Code:
+
+```bash
+claude mcp add pyxis -e PYXIS_TOKEN=pyxis_at_… -- npx -y pyxis-mcp
+```
+
+Claude Desktop (`claude_desktop_config.json`) and Cursor (`.cursor/mcp.json`):
+
+```json
+{
+  "mcpServers": {
+    "pyxis": {
+      "command": "npx",
+      "args": ["-y", "pyxis-mcp"],
+      "env": { "PYXIS_TOKEN": "pyxis_at_…" }
+    }
+  }
+}
+```
+
+A self-hosted Pyxis adds `PYXIS_API_URL`. To run it from source instead, `npm ci && npm run build`
+in a clone and use `node /path/to/pyxis-mcp/dist/cli.js` as the command. Keep the token out of
+shared files and chats; revoke it in the dashboard the moment it leaks.
+
+## Use it as a library
+
+Clients that only accept remote servers need the tools at a URL. The package exports them so a
+host can serve them from its own endpoint, over Streamable HTTP, with the token of whoever is
+calling. It is an ES module that a CommonJS host can also `require()` (Node 22.12 or later).
+
+```ts
+import { handleHttpRequest, PyxisApi } from 'pyxis-mcp';
+
+export function answerMcp(request: Request, callerToken: string): Promise<Response> {
+  const api = new PyxisApi({
+    token: callerToken,
+    apiUrl: 'https://api.pyxis-analytics.dev',
+    problemTexts: {
+      refusedToken: 'Pyxis refused this connection: connect Pyxis again in your MCP client.',
+      unreachableAdvice: 'Try again in a moment.',
+    },
+  });
+  return handleHttpRequest(request, api);
+}
+```
+
+| Export                                      | What it does                                                          |
+| ------------------------------------------- | --------------------------------------------------------------------- |
+| `handleHttpRequest(request, api, options?)` | Answers one MCP exchange: a web `Request` in, a web `Response` out    |
+| `createServer(api, options?)`               | The MCP server with the fifteen tools, for a transport of your choice |
+| `new PyxisApi(options)`                     | The client the tools read through, one per caller                     |
+
+`PyxisApi` options: `token` and `apiUrl` (required); `userAgent` (default `pyxis-mcp/<version>`);
+`fetch` (default the global one; a host can pass one that answers inside its own process);
+`timeoutMs` (default 15 seconds); `problemTexts`, the two sentences that depend on where the server
+runs: `refusedToken` and `unreachableAdvice` (default: the local server's, which name
+`PYXIS_TOKEN` and `PYXIS_API_URL`). `createServer` takes `version` (default the package's) and
+`now` (the clock); `handleHttpRequest` takes those and `allowedOrigins`.
+
+What the handler does: each request gets a server and a transport of its own, closed once it is
+answered, so there is no session id and no event stream, only JSON answers. It answers `405` with
+`Allow: POST` to any other method, `403` to a request with an `Origin` header unless that origin is
+in `allowedOrigins` (none by default: MCP clients do not call from web pages), and `413` to a body
+over 64 KiB. What it leaves to the host: authenticating the caller (and the `401` with
+`WWW-Authenticate` that starts a client's sign-in), rate limits and the host name
+([ADR 0003](docs/adr/0003-stateless-http-handler-for-hosts.md)).
+
+## Architecture
+
+```mermaid
+flowchart LR
+  Agent["MCP client<br>(Claude Code, Cursor…)"] -- "stdio, JSON-RPC" --> Server["pyxis-mcp<br>(on the user's machine)"]
+  Server -- "HTTPS GET<br>Authorization: Bearer pyxis_at_…" --> API["Pyxis API"]
+  Remote["Remote MCP client"] -- "Streamable HTTP POST<br>with the caller's token" --> Host["A host's endpoint<br>handleHttpRequest"]
+  Host -- "GET with the same token" --> API
+  API --> DB[("Events")]
+```
+
+The local server opens no port and keeps no state. The API decides what the token may read,
+exactly as it does for a dashboard session ([ADR 0002](docs/adr/0002-local-read-only-server.md)).
+A host runs the same tools for remote clients: it authenticates the caller, and the tools read with
+that caller's token, so the token never leaves the server that issued it
+([ADR 0003](docs/adr/0003-stateless-http-handler-for-hosts.md)).
+
+## Tech stack
+
+TypeScript (strict) on Node 22 or later, ES modules. Vitest with V8 coverage, ESLint
+(`typescript-eslint` strict, type-checked) and Prettier, Husky and commitlint, GitHub Actions with
+CodeQL, Dependabot and release-please.
+
+## Getting started
+
+```bash
+npm ci
+npm run lint && npm run typecheck && npm run test:cov && npm run build
+```
+
+## Testing
+
+- `npm run test:cov` runs the unit tests in Node and fails below **100%** of statements, branches,
+  functions and lines. The server is tested with a real MCP client over an in-memory transport and
+  a fake `fetch`; the HTTP handler with web `Request` objects, from `initialize` to a tool call,
+  and every refusal.
+- One file is left out of the unit coverage: `src/cli.ts`, which only wires the modules to the
+  standard input and output. `npm run test:e2e` covers it: after `npm run build`, a real MCP client
+  starts `dist/cli.js`, lists the tools and calls them against a local fake of the API, checks that
+  standard output carries nothing but the protocol, and that a bad configuration stops the process
+  with the reason on standard error.
+- `npm run test:e2e` also starts `e2e/http-host.ts`, a small HTTP host that imports `pyxis-mcp` by
+  its name, and drives it with the SDK's Streamable HTTP client: tools against the fake API with
+  the caller's token, no session, the host's own words for a refused token, `405` and `403`. The
+  package is also loaded by name with `import` and with `require`.
+- `src/contract.test.ts` checks the tools against `contract/openapi.json`, the API's own contract
+  (`npm run contract:sync` copies it from pyxis-api): every route a token may read has a tool, and
+  every tool sends only declared parameters, with values inside their enums.
+- `npm run test:tooling` tests the lint rule and the scripts.
+- CI runs the unit tests on Node 24 and again on Node 22, the oldest version the package supports.
+
+## Project structure
+
+```
+src/
+├── config.ts        reads PYXIS_TOKEN and PYXIS_API_URL
+├── pyxis-api.ts     one GET to the API, failures as sentences
+├── tools.ts         the fifteen tools: input schemas, routes, requests
+├── server.ts        registers the tools on the MCP server
+├── http.ts          one stateless Streamable HTTP exchange
+├── index.ts         the library's public exports
+├── version.ts       the package version, for the server and the user agent
+└── cli.ts           the executable: stdio transport
+e2e/                 the built package driven by real MCP clients, over stdio and over HTTP
+contract/            the API's OpenAPI contract, copied from pyxis-api
+eslint-rules/        the local rule that forbids comments
+scripts/             the comment check and the contract sync
+docs/adr/            architecture decision records
+```
+
+## Privacy and security
+
+- Read-only: the API accepts the token only on its read routes; it cannot write, sign in, manage
+  sessions or create tokens.
+- The token only travels in the `Authorization` header to the configured API, over https (plain
+  http only to localhost), and never reaches a log, an error message or a tool result.
+- Text written by a site's visitors is returned as data, and each tool description says it is not
+  an instruction.
+- Over HTTP, the handler keeps no session, refuses requests sent by web pages and bodies over 64
+  KiB, and reads with the token of the caller its host authenticated.
+- Vulnerabilities: see [SECURITY.md](SECURITY.md).
+
+## Architecture decisions
+
+| ADR                                                       | Decision                                                          |
+| --------------------------------------------------------- | ----------------------------------------------------------------- |
+| [0001](docs/adr/0001-record-architecture-decisions.md)    | Record architecture decisions                                     |
+| [0002](docs/adr/0002-local-read-only-server.md)           | A local, read-only server that uses the admin's access token      |
+| [0003](docs/adr/0003-stateless-http-handler-for-hosts.md) | A stateless HTTP handler that a host runs with the caller's token |
+
+## Roadmap
+
+- [x] Repository skeleton, quality gates, configuration reader
+- [x] Tools over the API's read routes, tested against its OpenAPI contract
+- [x] First release on npm, with provenance
+- [x] The tools as a library, served over stateless Streamable HTTP by a host
+- [ ] A remote endpoint in the Pyxis API, signed in with OAuth, for clients that only take URLs
+- [ ] Setup guides for Claude Code, Claude Desktop and Cursor
+
+## Contributing and license
+
+See [CONTRIBUTING.md](CONTRIBUTING.md) and the [Code of Conduct](CODE_OF_CONDUCT.md). MIT licensed:
+see [LICENSE](LICENSE).

package/dist/cli.d.ts

@@ -0,0 +1,2 @@
+#!/usr/bin/env node
+export {};

package/dist/cli.js

@@ -0,0 +1,18 @@
+#!/usr/bin/env node
+import { StdioServerTransport } from '@modelcontextprotocol/sdk/server/stdio.js';
+import { ConfigError, readConfig } from './config.js';
+import { PyxisApi } from './pyxis-api.js';
+import { createServer } from './server.js';
+const EXIT_FAILURE = 1;
+async function start() {
+    const server = createServer(new PyxisApi(readConfig(process.env)));
+    await server.connect(new StdioServerTransport());
+}
+start().catch((error) => {
+    const reason = error instanceof ConfigError
+        ? error.message
+        : `could not start: ${error instanceof Error ? `${error.name}: ${error.message}` : String(error)}`;
+    process.stderr.write(`pyxis-mcp: ${reason}\n`);
+    process.exitCode = EXIT_FAILURE;
+});
+//# sourceMappingURL=cli.js.map

package/dist/cli.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"cli.js","sourceRoot":"","sources":["../src/cli.ts"],"names":[],"mappings":";AACA,OAAO,EAAE,oBAAoB,EAAE,MAAM,2CAA2C,CAAC;AACjF,OAAO,EAAE,WAAW,EAAE,UAAU,EAAE,MAAM,aAAa,CAAC;AACtD,OAAO,EAAE,QAAQ,EAAE,MAAM,gBAAgB,CAAC;AAC1C,OAAO,EAAE,YAAY,EAAE,MAAM,aAAa,CAAC;AAE3C,MAAM,YAAY,GAAG,CAAC,CAAC;AAEvB,KAAK,UAAU,KAAK;IAClB,MAAM,MAAM,GAAG,YAAY,CAAC,IAAI,QAAQ,CAAC,UAAU,CAAC,OAAO,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC;IACnE,MAAM,MAAM,CAAC,OAAO,CAAC,IAAI,oBAAoB,EAAE,CAAC,CAAC;AACnD,CAAC;AAED,KAAK,EAAE,CAAC,KAAK,CAAC,CAAC,KAAc,EAAE,EAAE;IAC/B,MAAM,MAAM,GACV,KAAK,YAAY,WAAW;QAC1B,CAAC,CAAC,KAAK,CAAC,OAAO;QACf,CAAC,CAAC,oBAAoB,KAAK,YAAY,KAAK,CAAC,CAAC,CAAC,GAAG,KAAK,CAAC,IAAI,KAAK,KAAK,CAAC,OAAO,EAAE,CAAC,CAAC,CAAC,MAAM,CAAC,KAAK,CAAC,EAAE,CAAC;IACvG,OAAO,CAAC,MAAM,CAAC,KAAK,CAAC,cAAc,MAAM,IAAI,CAAC,CAAC;IAC/C,OAAO,CAAC,QAAQ,GAAG,YAAY,CAAC;AAClC,CAAC,CAAC,CAAC"}

package/dist/config.d.ts

@@ -0,0 +1,13 @@
+export declare const DEFAULT_API_URL = "https://api.pyxis-analytics.dev";
+export declare const ACCESS_TOKEN_PATTERN: RegExp;
+export interface PyxisConfig {
+    readonly token: string;
+    readonly apiUrl: string;
+}
+export type ConfigProblem = 'missing-token' | 'malformed-token' | 'invalid-api-url' | 'insecure-api-url';
+export declare class ConfigError extends Error {
+    readonly problem: ConfigProblem;
+    constructor(problem: ConfigProblem);
+}
+export type Environment = Readonly<Record<string, string | undefined>>;
+export declare function readConfig(environment: Environment): PyxisConfig;

package/dist/config.js

@@ -0,0 +1,64 @@
+export const DEFAULT_API_URL = 'https://api.pyxis-analytics.dev';
+export const ACCESS_TOKEN_PATTERN = /^pyxis_at_[A-Za-z0-9]{32}$/;
+const SECURE_PROTOCOL = 'https:';
+const LOCAL_PROTOCOL = 'http:';
+const LOCAL_HOSTS = new Set(['localhost', '127.0.0.1', '[::1]']);
+const ROOT_PATH = '/';
+const PROBLEM_MESSAGES = {
+    'missing-token': 'Set PYXIS_TOKEN to a read-only access token created in the Pyxis dashboard, under Settings, Access tokens.',
+    'malformed-token': 'PYXIS_TOKEN is not a Pyxis access token: it starts with pyxis_at_ followed by 32 letters and digits.',
+    'invalid-api-url': 'PYXIS_API_URL must be the address of a Pyxis API with no path, such as https://api.pyxis-analytics.dev.',
+    'insecure-api-url': 'PYXIS_API_URL must use https; plain http is accepted only for localhost.',
+};
+export class ConfigError extends Error {
+    problem;
+    constructor(problem) {
+        super(PROBLEM_MESSAGES[problem]);
+        this.problem = problem;
+        this.name = 'ConfigError';
+    }
+}
+export function readConfig(environment) {
+    return {
+        token: readToken(environment.PYXIS_TOKEN),
+        apiUrl: readApiUrl(environment.PYXIS_API_URL),
+    };
+}
+function readToken(raw) {
+    const token = raw?.trim() ?? '';
+    if (token === '') {
+        throw new ConfigError('missing-token');
+    }
+    if (!ACCESS_TOKEN_PATTERN.test(token)) {
+        throw new ConfigError('malformed-token');
+    }
+    return token;
+}
+function isBareOrigin(url) {
+    return (url.username === '' &&
+        url.password === '' &&
+        url.pathname === ROOT_PATH &&
+        url.search === '' &&
+        url.hash === '');
+}
+function readApiUrl(raw) {
+    const value = raw?.trim() ?? '';
+    if (value === '') {
+        return DEFAULT_API_URL;
+    }
+    const url = URL.parse(value);
+    if (url === null || !isBareOrigin(url)) {
+        throw new ConfigError('invalid-api-url');
+    }
+    if (url.protocol === SECURE_PROTOCOL) {
+        return url.origin;
+    }
+    if (url.protocol !== LOCAL_PROTOCOL) {
+        throw new ConfigError('invalid-api-url');
+    }
+    if (!LOCAL_HOSTS.has(url.hostname)) {
+        throw new ConfigError('insecure-api-url');
+    }
+    return url.origin;
+}
+//# sourceMappingURL=config.js.map

package/dist/config.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"config.js","sourceRoot":"","sources":["../src/config.ts"],"names":[],"mappings":"AAAA,MAAM,CAAC,MAAM,eAAe,GAAG,iCAAiC,CAAC;AACjE,MAAM,CAAC,MAAM,oBAAoB,GAAG,4BAA4B,CAAC;AAEjE,MAAM,eAAe,GAAG,QAAQ,CAAC;AACjC,MAAM,cAAc,GAAG,OAAO,CAAC;AAC/B,MAAM,WAAW,GAAwB,IAAI,GAAG,CAAC,CAAC,WAAW,EAAE,WAAW,EAAE,OAAO,CAAC,CAAC,CAAC;AACtF,MAAM,SAAS,GAAG,GAAG,CAAC;AAUtB,MAAM,gBAAgB,GAA4C;IAChE,eAAe,EACb,4GAA4G;IAC9G,iBAAiB,EACf,sGAAsG;IACxG,iBAAiB,EACf,yGAAyG;IAC3G,kBAAkB,EAAE,0EAA0E;CAC/F,CAAC;AAEF,MAAM,OAAO,WAAY,SAAQ,KAAK;IACf;IAArB,YAAqB,OAAsB;QACzC,KAAK,CAAC,gBAAgB,CAAC,OAAO,CAAC,CAAC,CAAC;QADd,YAAO,GAAP,OAAO,CAAe;QAEzC,IAAI,CAAC,IAAI,GAAG,aAAa,CAAC;IAC5B,CAAC;CACF;AAID,MAAM,UAAU,UAAU,CAAC,WAAwB;IACjD,OAAO;QACL,KAAK,EAAE,SAAS,CAAC,WAAW,CAAC,WAAW,CAAC;QACzC,MAAM,EAAE,UAAU,CAAC,WAAW,CAAC,aAAa,CAAC;KAC9C,CAAC;AACJ,CAAC;AAED,SAAS,SAAS,CAAC,GAAuB;IACxC,MAAM,KAAK,GAAG,GAAG,EAAE,IAAI,EAAE,IAAI,EAAE,CAAC;IAChC,IAAI,KAAK,KAAK,EAAE,EAAE,CAAC;QACjB,MAAM,IAAI,WAAW,CAAC,eAAe,CAAC,CAAC;IACzC,CAAC;IACD,IAAI,CAAC,oBAAoB,CAAC,IAAI,CAAC,KAAK,CAAC,EAAE,CAAC;QACtC,MAAM,IAAI,WAAW,CAAC,iBAAiB,CAAC,CAAC;IAC3C,CAAC;IACD,OAAO,KAAK,CAAC;AACf,CAAC;AAED,SAAS,YAAY,CAAC,GAAQ;IAC5B,OAAO,CACL,GAAG,CAAC,QAAQ,KAAK,EAAE;QACnB,GAAG,CAAC,QAAQ,KAAK,EAAE;QACnB,GAAG,CAAC,QAAQ,KAAK,SAAS;QAC1B,GAAG,CAAC,MAAM,KAAK,EAAE;QACjB,GAAG,CAAC,IAAI,KAAK,EAAE,CAChB,CAAC;AACJ,CAAC;AAED,SAAS,UAAU,CAAC,GAAuB;IACzC,MAAM,KAAK,GAAG,GAAG,EAAE,IAAI,EAAE,IAAI,EAAE,CAAC;IAChC,IAAI,KAAK,KAAK,EAAE,EAAE,CAAC;QACjB,OAAO,eAAe,CAAC;IACzB,CAAC;IACD,MAAM,GAAG,GAAG,GAAG,CAAC,KAAK,CAAC,KAAK,CAAC,CAAC;IAC7B,IAAI,GAAG,KAAK,IAAI,IAAI,CAAC,YAAY,CAAC,GAAG,CAAC,EAAE,CAAC;QACvC,MAAM,IAAI,WAAW,CAAC,iBAAiB,CAAC,CAAC;IAC3C,CAAC;IACD,IAAI,GAAG,CAAC,QAAQ,KAAK,eAAe,EAAE,CAAC;QACrC,OAAO,GAAG,CAAC,MAAM,CAAC;IACpB,CAAC;IACD,IAAI,GAAG,CAAC,QAAQ,KAAK,cAAc,EAAE,CAAC;QACpC,MAAM,IAAI,WAAW,CAAC,iBAAiB,CAAC,CAAC;IAC3C,CAAC;IACD,IAAI,CAAC,WAAW,CAAC,GAAG,CAAC,GAAG,CAAC,QAAQ,CAAC,EAAE,CAAC;QACnC,MAAM,IAAI,WAAW,CAAC,kBAAkB,CAAC,CAAC;IAC5C,CAAC;IACD,OAAO,GAAG,CAAC,MAAM,CAAC;AACpB,CAAC"}

package/dist/http.d.ts

@@ -0,0 +1,12 @@
+import type { PyxisApi } from './pyxis-api.js';
+import { type ServerOptions } from './server.js';
+export declare const MAX_REQUEST_BYTES: number;
+export declare const ALLOWED_METHOD = "POST";
+export declare const HTTP_REFUSALS: {
+    readonly method: "Method not allowed: this server keeps no session and answers POST only.";
+    readonly origin: "Forbidden: this server does not answer requests sent by a web page.";
+};
+export interface HttpOptions extends ServerOptions {
+    readonly allowedOrigins?: readonly string[];
+}
+export declare function handleHttpRequest(request: Request, api: PyxisApi, options?: HttpOptions): Promise<Response>;

package/dist/http.js

@@ -0,0 +1,44 @@
+import { WebStandardStreamableHTTPServerTransport } from '@modelcontextprotocol/sdk/server/webStandardStreamableHttp.js';
+import { createServer } from './server.js';
+export const MAX_REQUEST_BYTES = 64 * 1024;
+export const ALLOWED_METHOD = 'POST';
+export const HTTP_REFUSALS = {
+    method: 'Method not allowed: this server keeps no session and answers POST only.',
+    origin: 'Forbidden: this server does not answer requests sent by a web page.',
+};
+const STATUS_FORBIDDEN = 403;
+const STATUS_METHOD_NOT_ALLOWED = 405;
+const JSON_RPC_SERVER_ERROR = -32000;
+const JSON_MEDIA_TYPE = 'application/json';
+function refusal(status, message, headers = {}) {
+    return new Response(JSON.stringify({
+        jsonrpc: '2.0',
+        error: { code: JSON_RPC_SERVER_ERROR, message },
+        id: null,
+    }), { status, headers: { 'content-type': JSON_MEDIA_TYPE, ...headers } });
+}
+function comesFromForeignPage(request, allowedOrigins) {
+    const origin = request.headers.get('origin');
+    return origin !== null && !allowedOrigins.includes(origin);
+}
+export async function handleHttpRequest(request, api, options = {}) {
+    if (request.method !== ALLOWED_METHOD) {
+        return refusal(STATUS_METHOD_NOT_ALLOWED, HTTP_REFUSALS.method, { allow: ALLOWED_METHOD });
+    }
+    if (comesFromForeignPage(request, options.allowedOrigins ?? [])) {
+        return refusal(STATUS_FORBIDDEN, HTTP_REFUSALS.origin);
+    }
+    const server = createServer(api, options);
+    const transport = new WebStandardStreamableHTTPServerTransport({
+        enableJsonResponse: true,
+        maxRequestBodySize: MAX_REQUEST_BYTES,
+    });
+    await server.connect(transport);
+    try {
+        return await transport.handleRequest(request);
+    }
+    finally {
+        await server.close();
+    }
+}
+//# sourceMappingURL=http.js.map

package/dist/http.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"http.js","sourceRoot":"","sources":["../src/http.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,wCAAwC,EAAE,MAAM,+DAA+D,CAAC;AAEzH,OAAO,EAAE,YAAY,EAAsB,MAAM,aAAa,CAAC;AAE/D,MAAM,CAAC,MAAM,iBAAiB,GAAG,EAAE,GAAG,IAAI,CAAC;AAC3C,MAAM,CAAC,MAAM,cAAc,GAAG,MAAM,CAAC;AAErC,MAAM,CAAC,MAAM,aAAa,GAAG;IAC3B,MAAM,EAAE,yEAAyE;IACjF,MAAM,EAAE,qEAAqE;CACrE,CAAC;AAEX,MAAM,gBAAgB,GAAG,GAAG,CAAC;AAC7B,MAAM,yBAAyB,GAAG,GAAG,CAAC;AACtC,MAAM,qBAAqB,GAAG,CAAC,KAAK,CAAC;AACrC,MAAM,eAAe,GAAG,kBAAkB,CAAC;AAM3C,SAAS,OAAO,CAAC,MAAc,EAAE,OAAe,EAAE,UAAkC,EAAE;IACpF,OAAO,IAAI,QAAQ,CACjB,IAAI,CAAC,SAAS,CAAC;QACb,OAAO,EAAE,KAAK;QACd,KAAK,EAAE,EAAE,IAAI,EAAE,qBAAqB,EAAE,OAAO,EAAE;QAC/C,EAAE,EAAE,IAAI;KACT,CAAC,EACF,EAAE,MAAM,EAAE,OAAO,EAAE,EAAE,cAAc,EAAE,eAAe,EAAE,GAAG,OAAO,EAAE,EAAE,CACrE,CAAC;AACJ,CAAC;AAED,SAAS,oBAAoB,CAAC,OAAgB,EAAE,cAAiC;IAC/E,MAAM,MAAM,GAAG,OAAO,CAAC,OAAO,CAAC,GAAG,CAAC,QAAQ,CAAC,CAAC;IAC7C,OAAO,MAAM,KAAK,IAAI,IAAI,CAAC,cAAc,CAAC,QAAQ,CAAC,MAAM,CAAC,CAAC;AAC7D,CAAC;AAED,MAAM,CAAC,KAAK,UAAU,iBAAiB,CACrC,OAAgB,EAChB,GAAa,EACb,UAAuB,EAAE;IAEzB,IAAI,OAAO,CAAC,MAAM,KAAK,cAAc,EAAE,CAAC;QACtC,OAAO,OAAO,CAAC,yBAAyB,EAAE,aAAa,CAAC,MAAM,EAAE,EAAE,KAAK,EAAE,cAAc,EAAE,CAAC,CAAC;IAC7F,CAAC;IACD,IAAI,oBAAoB,CAAC,OAAO,EAAE,OAAO,CAAC,cAAc,IAAI,EAAE,CAAC,EAAE,CAAC;QAChE,OAAO,OAAO,CAAC,gBAAgB,EAAE,aAAa,CAAC,MAAM,CAAC,CAAC;IACzD,CAAC;IACD,MAAM,MAAM,GAAG,YAAY,CAAC,GAAG,EAAE,OAAO,CAAC,CAAC;IAC1C,MAAM,SAAS,GAAG,IAAI,wCAAwC,CAAC;QAC7D,kBAAkB,EAAE,IAAI;QACxB,kBAAkB,EAAE,iBAAiB;KACtC,CAAC,CAAC;IACH,MAAM,MAAM,CAAC,OAAO,CAAC,SAAS,CAAC,CAAC;IAChC,IAAI,CAAC;QACH,OAAO,MAAM,SAAS,CAAC,aAAa,CAAC,OAAO,CAAC,CAAC;IAChD,CAAC;YAAS,CAAC;QACT,MAAM,MAAM,CAAC,KAAK,EAAE,CAAC;IACvB,CAAC;AACH,CAAC"}

package/dist/index.d.ts

@@ -0,0 +1,3 @@
+export { handleHttpRequest, type HttpOptions } from './http.js';
+export { PyxisApi, type ApiOutcome, type Fetch, type ProblemTexts, type PyxisApiOptions, type Query, type QueryValue, } from './pyxis-api.js';
+export { createServer, type ServerOptions } from './server.js';

package/dist/index.js

@@ -0,0 +1,4 @@
+export { handleHttpRequest } from './http.js';
+export { PyxisApi, } from './pyxis-api.js';
+export { createServer } from './server.js';
+//# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,iBAAiB,EAAoB,MAAM,WAAW,CAAC;AAChE,OAAO,EACL,QAAQ,GAOT,MAAM,gBAAgB,CAAC;AACxB,OAAO,EAAE,YAAY,EAAsB,MAAM,aAAa,CAAC"}

package/dist/pyxis-api.d.ts

@@ -0,0 +1,40 @@
+import type { PyxisConfig } from './config.js';
+export declare const REQUEST_TIMEOUT_MS = 15000;
+export declare const REQUESTS_PER_MINUTE = 60;
+export type QueryValue = string | number | boolean | readonly string[] | undefined;
+export type Query = Readonly<Record<string, QueryValue>>;
+export type ApiOutcome = {
+    readonly ok: true;
+    readonly body: unknown;
+} | {
+    readonly ok: false;
+    readonly problem: string;
+};
+export type Fetch = (url: string, init: RequestInit) => Promise<Response>;
+export interface ProblemTexts {
+    readonly refusedToken: string;
+    readonly unreachableAdvice: string;
+}
+export declare const LOCAL_PROBLEM_TEXTS: ProblemTexts;
+export interface PyxisApiOptions extends PyxisConfig {
+    readonly userAgent?: string;
+    readonly fetch?: Fetch;
+    readonly timeoutMs?: number;
+    readonly problemTexts?: ProblemTexts;
+}
+export declare const PROBLEMS: {
+    readonly notFound: "Not found: no project with this id among the projects this token can read. Call list_projects for the ids.";
+    readonly rejected: "The Pyxis API refused the request.";
+    readonly notJson: "The Pyxis API answered with something that is not JSON.";
+};
+export declare function requestUrl(apiUrl: string, path: string, query: Query): string;
+export declare class PyxisApi {
+    private readonly token;
+    private readonly apiUrl;
+    private readonly userAgent;
+    private readonly fetch;
+    private readonly timeoutMs;
+    private readonly problemTexts;
+    constructor(options: PyxisApiOptions);
+    get(path: string, query?: Query): Promise<ApiOutcome>;
+}