@atollhq/mcp-server 0.1.0

package/README.md

@@ -0,0 +1,89 @@
+# @atollhq/mcp-server
+
+Remote-capable MCP server for Atoll. It mirrors the core `@atollhq/cli` workflows as MCP tools while calling the Atoll REST API directly, so clients do not need local Atoll CLI profiles or filesystem access.
+
+## Install
+
+```bash
+npm install -g @atollhq/mcp-server
+```
+
+## Remote HTTP
+
+```bash
+PORT=8787 atoll-mcp
+```
+
+The server exposes:
+
+- `POST /mcp` -- MCP Streamable HTTP endpoint
+- `GET /health` -- JSON health check
+
+Remote clients should send the Atoll API key per request:
+
+```http
+Authorization: Bearer sk_atoll_...
+```
+
+For single-tenant deployments, set:
+
+```bash
+export ATOLL_API_KEY="sk_atoll_..."
+export ATOLL_ORG_ID="org-uuid"
+export ATOLL_BASE_URL="https://atollhq.com"
+```
+
+When `org_id` is omitted from a tool call, the server uses `ATOLL_ORG_ID`. If that is not set, it uses the only org visible to the API key. If multiple orgs are visible, tools return an error asking for `org_id`.
+
+## Local stdio
+
+```bash
+ATOLL_API_KEY=sk_atoll_... ATOLL_ORG_ID=org-uuid atoll-mcp --stdio
+```
+
+## Tool coverage
+
+The MCP surface uses service-prefixed tool names to avoid collisions:
+
+- `atoll_get_heartbeat`
+- `atoll_list_orgs`, `atoll_get_auth_context`
+- `atoll_list_issues`, `atoll_get_issue`, `atoll_create_issue`, `atoll_update_issue`, `atoll_archive_issue`, `atoll_unarchive_issue`
+- `atoll_list_comments`, `atoll_add_comment`
+- `atoll_list_projects`, `atoll_get_project`, `atoll_create_project`
+- `atoll_list_goals`, `atoll_get_goal`, `atoll_create_goal`, `atoll_update_goal`
+- `atoll_list_kpis`, `atoll_get_kpi`, `atoll_create_kpi`, `atoll_update_kpi`, `atoll_list_kpi_snapshots`, `atoll_record_kpi_snapshot`
+- `atoll_create_kpi_http_sync_draft`, `atoll_validate_kpi_http_sync_config` for draft-only KPI sync setup
+- `atoll_list_initiatives`, `atoll_get_initiative`, `atoll_create_initiative`, `atoll_update_initiative`, initiative link tools
+- `atoll_list_milestones`, `atoll_create_milestone`, `atoll_upsert_milestone`
+- `atoll_list_dependencies`, `atoll_add_dependency`, `atoll_remove_dependency`
+- `atoll_list_webhooks`, `atoll_create_webhook`, `atoll_delete_webhook`
+- `atoll_send_feedback`
+- `atoll_api_request` for advanced REST endpoints not yet promoted to a first-class tool
+
+`atoll_update_issue` accepts `comment_body` and `commentBody` with status updates. Use this when applying a heartbeat `start_work` recommendation so the KPI, initiative, initiative target, why-now, expected impact, first step, and success criteria remain as a durable issue comment while the issue status changes.
+
+KPI HTTP sync admin routes are intentionally blocked from `atoll_api_request`. Use `atoll_create_kpi_http_sync_draft` or `atoll_validate_kpi_http_sync_config` for agent-authored drafts; human admins must use Atoll for exact-host allowlists, secret entry, dry-runs, publishing, disabling, and run-now snapshot writes.
+
+## Skills packaging
+
+Keep Atoll skills separate from this MCP server.
+
+The MCP package should stay runtime-focused: transport, auth, validation, Atoll API calls, and structured tool responses. Skills are client-side agent guidance and already differ by environment (`skill-claude`, `skill-codex`, `skill-gemini`, ClawHub). The server exposes an `atoll://skills/packaging` resource that explains this decision to MCP clients, but it does not bundle local skill files.
+
+## ChatGPT app path
+
+OpenAI’s Apps SDK builds ChatGPT apps around an MCP server plus optional UI components. The next step is to make this package deployable at a public HTTPS URL, add OAuth or API-key setup for ChatGPT users, then add Apps SDK resources/components for richer Atoll views such as heartbeat, board, issue detail, and KPI trend panels.
+
+Useful official starting points:
+
+- `https://developers.openai.com/apps-sdk/`
+- `https://developers.openai.com/apps-sdk/build/mcp-server`
+- `https://developers.openai.com/apps-sdk/build/components`
+- `https://developers.openai.com/apps-sdk/build/auth`
+
+## Development
+
+```bash
+bun test packages/mcp-server/test/*.test.ts
+bun run --cwd packages/mcp-server build
+```

package/dist/index.d.ts

@@ -0,0 +1,45 @@
+import * as node_http from 'node:http';
+import { IncomingMessage, ServerResponse } from 'node:http';
+import { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
+
+interface AtollApiClientOptions {
+    apiKey: string;
+    baseUrl?: string;
+    timeoutMs?: number;
+    fetch?: typeof fetch;
+}
+declare class AtollApiClient {
+    readonly baseUrl: string;
+    private readonly apiKey;
+    private readonly timeoutMs;
+    private readonly fetchImpl;
+    constructor(options: AtollApiClientOptions);
+    request<T = unknown>(method: string, path: string, body?: unknown): Promise<T>;
+    get<T = unknown>(path: string): Promise<T>;
+    post<T = unknown>(path: string, body?: unknown): Promise<T>;
+    put<T = unknown>(path: string, body?: unknown): Promise<T>;
+    patch<T = unknown>(path: string, body?: unknown): Promise<T>;
+    delete<T = unknown>(path: string): Promise<T>;
+}
+declare function resolveAuthToken(authorizationHeader?: string): string;
+declare function resolveOrgId(client: AtollApiClient, explicitOrgId?: string): Promise<string>;
+
+interface HealthResponse {
+    status: number;
+    headers: Record<string, string>;
+    body: string;
+}
+declare function extractBearerToken(header?: string): string | undefined;
+declare function healthResponse(): HealthResponse;
+declare function handleMcpHttpRequest(req: IncomingMessage, res: ServerResponse): Promise<void>;
+declare function createAtollHttpServer(): node_http.Server<typeof IncomingMessage, typeof ServerResponse>;
+
+declare function listAtollToolNames(): string[];
+interface AtollMcpServer {
+    server: McpServer;
+    instructions: string;
+    toolNames: string[];
+}
+declare function createAtollMcpServer(): AtollMcpServer;
+
+export { AtollApiClient, createAtollHttpServer, createAtollMcpServer, extractBearerToken, handleMcpHttpRequest, healthResponse, listAtollToolNames, resolveAuthToken, resolveOrgId };