coss-mcp 0.0.0-stage → 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Cal.com, Inc.
+
+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,3 +1,68 @@
-# Temporary Holding Version
+# coss-mcp
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+The [Model Context Protocol](https://modelcontextprotocol.io) server for [COSS](https://coss.com). Your
+coding agent can ask "did the welcome email to jane@example.com get delivered?" and get the answer:
+the email, what happened to each recipient and why, and what to do about it.
+
+```sh
+claude mcp add coss -e COSS_API_KEY=coss_test_… -- npx -y coss-mcp
+```
+
+Any MCP client works the same way: run `npx -y coss-mcp` with `COSS_API_KEY` in its environment.
+Setup for Cursor, VS Code and Codex: [coss.com/docs/mcp](https://coss.com/docs/mcp).
+
+Published from [cosscom/coss](https://github.com/cosscom/coss) by CI, with
+[provenance](https://docs.npmjs.com/generating-provenance-statements).
+
+## Configuration
+
+| Variable | |
+| --- | --- |
+| `COSS_API_KEY` | Required. A `coss_test_…` (development) or `coss_live_…` (production) key; the server sees that key's environment. |
+| `COSS_BASE_URL` | Another API origin, e.g. `http://localhost:3001`. Defaults to `https://api.coss.com`. |
+
+Configuration is read from the environment only, never from command-line arguments, which other
+local processes can read.
+
+API keys can do everything the API can: through this server the agent can also send email and
+change suppressions and domains. Tools are annotated (`readOnlyHint`, `destructiveHint`) so clients
+can ask before calling the ones that change something.
+
+## Tools
+
+| Area | Tools |
+| --- | --- |
+| Email delivery | `diagnose_email`, `find_emails`, `get_email` |
+| Sending | `send_email`, `cancel_email`, `reschedule_email` |
+| Suppressions | `check_suppression`, `list_suppressions`, `add_suppression`, `remove_suppression` |
+| Domains | `list_domains`, `get_domain`, `add_domain`, `verify_domain` |
+| Webhooks | `list_webhook_endpoints`, `list_webhook_deliveries`, `get_webhook_delivery`, `retry_webhook_delivery` |
+| Receiving | `get_inbound_address`, `list_received_emails`, `get_received_email` |
+| Logs | `search_logs`, `get_log` |
+| Account | `get_account_status` |
+
+## As a library
+
+`createCossMcpServer` returns the server unconnected, for another transport or an existing client:
+
+```ts
+import { Coss } from "coss";
+import { createCossMcpServer } from "coss-mcp";
+
+const apiKey = process.env.COSS_API_KEY;
+const server = createCossMcpServer({ coss: new Coss({ apiKey }), apiKey });
+```
+
+`diagnoseEmail({ email, events, context })` is the pure function behind `diagnose_email`.
+
+## Development
+
+```sh
+bun run --cwd packages/mcp build   # tsdown, publint, attw
+bun run --cwd packages/mcp test
+COSS_API_KEY=coss_test_… COSS_BASE_URL=http://localhost:3001 npx @modelcontextprotocol/inspector node packages/mcp/dist/cli.js
+```
+
+## License
+
+MIT

package/dist/cli.d.ts

@@ -0,0 +1 @@
+export {}

package/dist/cli.js

@@ -0,0 +1,25 @@
+#!/usr/bin/env node
+import { t as createCossMcpServer } from "./server-BEFSDUL2.js";
+import { serveStdio } from "@modelcontextprotocol/server/stdio";
+import { Coss } from "coss";
+//#region src/cli.ts
+/**
+* `npx coss-mcp`: the COSS MCP server over stdio. Configuration comes from the environment only
+* (never argv, which other local processes can read): COSS_API_KEY, and COSS_BASE_URL to point
+* at another API (e.g. http://localhost:3001). stdout carries the protocol; logs go to stderr.
+*/
+const apiKey = process.env.COSS_API_KEY?.trim();
+if (!apiKey) {
+	console.error("coss-mcp: set COSS_API_KEY to a COSS API key (create one in the dashboard: https://coss.com/dashboard).");
+	process.exit(1);
+}
+const coss = new Coss({
+	apiKey,
+	baseUrl: process.env.COSS_BASE_URL?.trim() || void 0
+});
+serveStdio(() => createCossMcpServer({
+	coss,
+	apiKey
+}), { onerror: (error) => console.error("coss-mcp:", error) });
+//#endregion
+export {};

package/dist/index.d.ts

@@ -0,0 +1,86 @@
+import { McpServer } from "@modelcontextprotocol/server";
+import { Coss, Email, EmailEvent, EmailRecipient, EmailSummary, ReputationStatus, Suppression } from "coss";
+//#region src/diagnose.d.ts
+type RecipientOutcome = "delivered" | "in_progress" | "delayed" | "bounced" | "complained" | "suppressed" | "failed" | "scheduled" | "canceled";
+type Verdict = "delivered" | "partially_delivered" | "in_progress" | "scheduled" | "canceled" | "not_delivered";
+interface RecipientDiagnosis {
+  address: string;
+  type: EmailRecipient["type"];
+  status: EmailRecipient["status"];
+  outcome: RecipientOutcome;
+  explanation: string;
+  /** The receiving server's or provider's own words, when there are any. */
+  details?: Record<string, unknown>;
+  next_steps: string[];
+}
+interface Diagnosis {
+  email_id: string;
+  subject: string;
+  from: string;
+  status: Email["status"];
+  sandbox: boolean;
+  verdict: Verdict;
+  summary: string;
+  failure: {
+    code: string;
+    message: string;
+    explanation: string;
+    next_steps: string[];
+  } | null;
+  recipients: RecipientDiagnosis[];
+  /** Account or setup problems that affect this email or the next ones. */
+  warnings: string[];
+  timeline: {
+    at: string;
+    type: string;
+    recipient: string | null;
+  }[];
+  created_at: string;
+  sent_at: string | null;
+  scheduled_at: string | null;
+}
+interface DiagnosisContext {
+  /** Suppression entries of recipient addresses (from `check_suppression`). */
+  suppressions?: Record<string, Suppression[]>;
+  /** The From address's domain, as COSS has it; `null` when no domain matched. */
+  domain?: {
+    name: string;
+    status: string;
+    can_send: boolean;
+  } | null;
+  reputation?: {
+    status: ReputationStatus;
+    reason: string | null;
+  } | null;
+  billing?: {
+    status: string;
+    holds: {
+      reason: string;
+      since: string;
+    }[];
+  } | null;
+}
+export declare function diagnoseEmail(input: {
+  email: Email | EmailSummary;
+  events: EmailEvent[];
+  context?: DiagnosisContext;
+  now?: Date;
+}): Diagnosis;
+//#endregion
+//#region src/server.d.ts
+interface CossMcpServerOptions {
+  /** The client every tool calls. */
+  coss: Coss;
+  /** The client's API key, only to tell live from sandbox keys (never sent anywhere else). */
+  apiKey?: string;
+  /** Overrides `new Date()` (tests). */
+  now?: () => Date;
+}
+/** An MCP server exposing COSS's tools over any transport (`coss-mcp` uses stdio). */
+export declare function createCossMcpServer(options: CossMcpServerOptions): McpServer;
+//#endregion
+//#region src/version.d.ts
+/** The package version, sent as the server's version and in the SDK's user agent. */
+export declare const VERSION: string;
+//#endregion
+export type { CossMcpServerOptions, Diagnosis, DiagnosisContext, RecipientDiagnosis, RecipientOutcome, Verdict };

package/dist/index.js

@@ -0,0 +1 @@
+export { n as VERSION, t as createCossMcpServer, r as diagnoseEmail } from "./server-BEFSDUL2.js";