@wrongstack/mcp 0.1.2 → 0.1.4

package/LICENSE

@@ -1,17 +1,21 @@
-                                 Apache License
-                           Version 2.0, January 2004
-                        http://www.apache.org/licenses/
+MIT License
 
-   Copyright 2026 ECOSTACK TECHNOLOGY OÜ
+Copyright (c) 2026 ECOSTACK TECHNOLOGY OÜ
 
-   Licensed under the Apache License, Version 2.0 (the "License");
-   you may not use this file except in compliance with the License.
-   You may obtain a copy of the License at
+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:
 
-       http://www.apache.org/licenses/LICENSE-2.0
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
 
-   Unless required by applicable law or agreed to in writing, software
-   distributed under the License is distributed on an "AS IS" BASIS,
-   WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
-   See the License for the specific language governing permissions and
-   limitations under the License.
+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

@@ -0,0 +1,198 @@
+# MCP Servers — WrongStack
+
+Connect any [Model Context Protocol](https://modelcontextprotocol.io) server to WrongStack and use its tools as if they were built-in.
+
+## Supported Transports
+
+| Transport | Description |
+|-----------|-------------|
+| `stdio` | Spawns a local binary; communicates over stdin/stdout |
+| `sse` | HTTP Server-Sent Events for server events; HTTP POST for requests |
+| `streamable-http` | Session-based HTTP with NDJSON responses |
+
+## Quick Start
+
+```json
+// ~/.wrongstack/config.json
+{
+  "mcpServers": {
+    "filesystem": {
+      "enabled": true
+    }
+  }
+}
+```
+
+Then run `wstack` — the filesystem server is now active with tools like `mcp__filesystem__read_file`, `mcp__filesystem__write_file`, etc.
+
+## Built-in Server Presets
+
+WrongStack bundles configs for popular MCP servers. Enable them with:
+
+```bash
+# Add a server (disabled by default)
+wstack mcp add filesystem
+
+# Add and enable immediately
+wstack mcp add github --enable
+
+# List configured servers
+wstack mcp list
+```
+
+### Available Presets
+
+| Name | Transport | Description | Requires |
+|------|-----------|-------------|----------|
+| `filesystem` | stdio | Read, write, list, and search local files | — |
+| `github` | stdio | Issues, PRs, repos, search, file operations | `GITHUB_PERSONAL_ACCESS_TOKEN` |
+| `context7` | streamable-http | Codebase-aware documentation and Q&A | — |
+| `brave-search` | stdio | Web search | `BRAVE_SEARCH_API_KEY` (free 2k/month) |
+| `block` | stdio | Postgres via SQL | — |
+| `everart` | stdio | AI image generation | `EVERART_API_KEY` |
+| `slack` | stdio | Messaging, channels, search | `SLACK_BOT_TOKEN` + `SLACK_TEAM_ID` |
+| `aws` | stdio | EC2, S3, Lambda, IAM, CloudFormation | AWS credentials |
+| `google-maps` | stdio | Directions, geocoding, places | `GOOGLE_MAPS_API_KEY` |
+| `sentinel` | streamable-http | Security vulnerability scanning | — |
+
+## Manual Configuration
+
+```json
+{
+  "mcpServers": {
+    "my-server": {
+      "name": "my-server",
+      "description": "My custom MCP server",
+      "transport": "stdio",
+      "command": "npx",
+      "args": ["-y", "@my-org/mcp-server", "--verbose"],
+      "enabled": true,
+      "permission": "confirm",
+      "allowedTools": ["read", "search"],
+      "startupTimeoutMs": 10000
+    }
+  }
+}
+```
+
+### Configuration Reference
+
+```typescript
+interface MCPServerConfig {
+  name: string;
+  transport: 'stdio' | 'sse' | 'streamable-http';
+
+  // stdio — local binary
+  command?: string;    // e.g. "npx", "/usr/local/bin/my-mcp-server"
+  args?: string[];
+  env?: Record<string, string>;
+
+  // sse / streamable-http — remote
+  url?: string;
+  headers?: Record<string, string>;
+
+  // Common options
+  enabled?: boolean;          // default: true
+  allowedTools?: string[];    // whitelist — undefined = all tools
+  permission?: Permission;    // 'auto' | 'confirm' | 'deny'  (default: 'confirm')
+  startupTimeoutMs?: number;  // default: 10000
+  description?: string;        // shown in `wstack mcp list`
+}
+```
+
+## MCP Tool Naming
+
+All MCP tools are prefixed with `mcp__<server-name>__` to prevent collision:
+
+```
+mcp__github__list_issues
+mcp__github__create_pull_request
+mcp__filesystem__read_file
+mcp__filesystem__write_file
+```
+
+This means you can have a built-in `read_file` tool AND `mcp__filesystem__read_file` without conflict.
+
+## Permission Model
+
+All MCP tools default to `permission: 'confirm'` regardless of whether they look read-only. This means the agent asks before using them. You can:
+
+1. **Trust a server** — set `permission: 'auto'` in the server config (all tools run without asking)
+2. **Trust specific tools** — use a trust policy config (see `Config` type):
+   ```json
+   { "mcp__github__*": { "auto": true } }
+   ```
+3. **Deny a server** — set `permission: 'deny'` (tools exist but agent must explicitly request confirmation)
+
+## Reconnection
+
+- **stdio servers**: If the child process exits, WrongStack automatically retries up to 3 times with exponential backoff (500ms → 1s → 2s). After 3 failures the server is marked `failed` and tools are unregistered.
+- **HTTP servers (SSE / streamable-http)**: If the SSE read loop errors, the transport transitions to `disconnected` and the registry schedules a reconnect.
+
+## Troubleshooting
+
+### Server fails to start
+
+Check that:
+- The `command` is in your `PATH` (or use an absolute path)
+- `npx -y @modelcontextprotocol/server-filesystem .` works standalone
+- The `startupTimeoutMs` is sufficient for slow-starting servers
+
+### Tools not appearing
+
+```bash
+wstack mcp list          # shows configured servers + state
+wstack diag              # shows MCP health under "MCP Servers:"
+```
+
+### Connection drops repeatedly
+
+This usually means the server process crashes on startup. Try running it manually:
+```bash
+node /path/to/server/script.js
+# then type: {"jsonrpc":"2.0","id":1,"method":"initialize","params":{...}}
+```
+
+### `allowedTools` not filtering
+
+Restart after changing `allowedTools` — the tool list is cached after discovery.
+
+## Writing Your Own MCP Server
+
+Any server that implements the [MCP spec](https://spec.modelcontextprotocol.io) works with WrongStack. Minimal example:
+
+```typescript
+// server.js — stdio MCP server
+import { createInterface } from 'readline';
+
+const rl = createInterface({ input: process.stdin, terminal: false });
+rl.on('line', async (line) => {
+  const req = JSON.parse(line);
+  if (req.method === 'initialize') {
+    process.stdout.write(JSON.stringify({
+      jsonrpc: '2.0', id: req.id,
+      result: { protocolVersion: '2024-11-05', capabilities: { tools: {} }, serverInfo: { name: 'my-server', version: '1.0.0' } }
+    }) + '\n');
+    process.stdout.flush();
+  } else if (req.method === 'tools/list') {
+    process.stdout.write(JSON.stringify({
+      jsonrpc: '2.0', id: req.id,
+      result: { tools: [{ name: 'greet', description: 'Say hello', inputSchema: { type: 'object', properties: { name: { type: 'string' } } } }] }
+    }) + '\n');
+    process.stdout.flush();
+  }
+});
+```
+
+Then in your config:
+```json
+{
+  "mcpServers": {
+    "my-server": {
+      "transport": "stdio",
+      "command": "node",
+      "args": ["/path/to/server.js"]
+    }
+  }
+}
+```

package/dist/index.d.ts

@@ -21,9 +21,18 @@ interface ToolCallResult {
     content: unknown;
     isError: boolean;
 }
+type ExitListener = (name: string, code: number | null, signal: string | null) => void;
 /**
- * Lightweight stdio MCP client. Supports JSON-RPC 2.0 over newline-delimited JSON.
- * SSE / streamable-http are stubbed and throw on connect — to be filled by a real impl.
+ * Fired when the server sends `notifications/tools/list_changed`. The
+ * client refreshes its cached tool list before invoking listeners, so
+ * subscribers can call `listTools()` for the fresh set.
+ */
+type ToolsChangedListener = (name: string, tools: MCPTool[]) => void;
+/**
+ * Lightweight MCP client supporting three transport types:
+ * - stdio: spawns a child process and communicates over pipes
+ * - sse: connects to an HTTP SSE endpoint for server events, POST for requests
+ * - streamable-http: session-based HTTP transport with NDJSON responses
  */
 declare class MCPClient {
     readonly opts: MCPClientOptions;
@@ -32,27 +41,55 @@ declare class MCPClient {
     private nextId;
     private readonly pending;
     private rxBuffer;
-    private tools;
-    /**
-     * Guards against multiple concurrent drain-waits. When `stdin.write()`
-     * returns false the first waiter sets this flag; any subsequent callers
-     * skip the drain wait and emit a warning instead of racing.
-     */
+    private _tools;
+    /** Cached tool list — survives reconnects so the registry can re-register without re-discovering. */
+    private _toolsCache?;
     private _drainPending;
-    /** Set when a notify() call failed for reasons the caller should know about. */
     private _lastNotifySkipped;
+    private sseTransport?;
+    private httpTransport?;
+    /** Notified when the stdio child process exits so the registry can attempt reconnect. */
+    private readonly exitListeners;
+    /** Notified when the server announces a tools/list_changed notification. */
+    private readonly toolsChangedListeners;
+    /** Notified when an HTTP transport (SSE or streamable-http) disconnects. */
+    private readonly disconnectListeners;
     constructor(opts: MCPClientOptions);
     getState(): ConnectionState;
     listTools(): MCPTool[];
     /** Returns true if a prior notify() call was skipped due to backpressure. */
     hadNotifySkipped(): boolean;
+    /**
+     * Register a listener for child-process exit events.
+     * The registry uses this to trigger reconnection.
+     */
+    addExitListener(listener: ExitListener): void;
+    removeExitListener(listener: ExitListener): void;
+    /**
+     * Register a listener for transport disconnect events (SSE / streamable-http).
+     * Used by the registry to trigger reconnection for HTTP-based servers.
+     */
+    addDisconnectListener(listener: () => void): void;
+    removeDisconnectListener(listener: () => void): void;
     connect(): Promise<void>;
+    private connectStdio;
+    private connectSSE;
+    private connectStreamableHTTP;
     callTool(name: string, input: unknown): Promise<ToolCallResult>;
     close(): Promise<void>;
     private request;
     private notify;
     private onData;
     private onLine;
+    /**
+     * L2-C: refresh the cached tool list when the server announces a
+     * `tools/list_changed`. Listeners (the registry) re-wrap and
+     * re-register. Failures are swallowed — a stale cache is preferable
+     * to a hard crash on a transient notification glitch.
+     */
+    private handleToolsListChanged;
+    addToolsChangedListener(listener: ToolsChangedListener): void;
+    removeToolsChangedListener(listener: ToolsChangedListener): void;
 }
 
 declare function wrapMCPTool(serverName: string, mcpTool: MCPTool, client: MCPClient, permission?: Permission): Tool;
@@ -77,7 +114,130 @@ declare class MCPRegistry {
         toolCount: number;
     }[];
     stopAll(): Promise<void>;
+    /**
+     * Health check — returns 'ok' for connected servers, the current state otherwise.
+     * For HTTP-based transports this could also ping the server.
+     */
+    health(): {
+        name: string;
+        alive: boolean;
+        latencyMs?: number;
+    }[];
+    /**
+     * L2-C: handle `notifications/tools/list_changed` from the server.
+     * Unregister the previous wrapper set, then re-register the fresh
+     * tool list. The client has already refreshed its cache before
+     * dispatching — we just need to re-wrap and re-register.
+     */
+    private readonly onToolsChanged;
+    private readonly onChildExit;
+    /** Handles SSE / streamable-http disconnect — same recovery as stdio child exit. */
+    private readonly onTransportDisconnect;
+    /**
+     * L2-B: maximum number of reconnect cycles before staying `failed`.
+     * One cycle = one full `attemptConnect` (which itself may try up to 3
+     * times). Caps total reconnect storm at ~5 cycles, then the slot
+     * needs an explicit `restart()` to re-engage.
+     */
+    private static readonly MAX_RECONNECT_CYCLES;
+    /** Base delay between cycles, in ms. Real delay adds jitter. */
+    private static readonly BASE_RECONNECT_DELAY_MS;
+    /** Hard ceiling on the inter-cycle delay so the user doesn't wait minutes. */
+    private static readonly MAX_RECONNECT_DELAY_MS;
+    private scheduleReconnect;
+    private attemptReconnect;
     private attemptConnect;
 }
 
-export { type ConnectionState, MCPClient, type MCPClientOptions, MCPRegistry, type MCPRegistryOptions, type MCPTool, type ToolCallResult, type Transport, wrapMCPTool };
+interface HttpTransportOptions {
+    name: string;
+    url: string;
+    headers?: Record<string, string>;
+    startupTimeoutMs?: number;
+}
+/**
+ * SSE-based MCP transport using native fetch.
+ *
+ * Communication pattern:
+ * - Client connects to SSE endpoint to receive server messages (JSON-RPC events)
+ * - Client sends JSON-RPC requests via HTTP POST to the same or separate endpoint
+ * - Server sends results/errors via the SSE stream
+ *
+ * The SSE reader parses the SSE protocol (event:, data:, blank line to dispatch).
+ */
+declare class SSEReader {
+    private buffer;
+    private listeners;
+    onMessage(cb: (data: {
+        jsonrpc?: string;
+        method?: string;
+        params?: unknown;
+        id?: number;
+    }) => void): () => void;
+    feed(chunk: string): void;
+    private dispatch;
+    reset(): void;
+}
+/**
+ * SSE transport for MCP over HTTP.
+ *
+ * Uses native fetch API with ReadableStream to consume SSE events.
+ * HTTP POST is used to send JSON-RPC requests.
+ */
+declare class SSETransport {
+    private state;
+    private url;
+    private headers;
+    private timeout;
+    private nextId;
+    private pending;
+    private tools;
+    private abortController?;
+    private reader?;
+    private readerDone;
+    private disconnectHandlers;
+    private readLoopAbort?;
+    private readonly toolsChangedListeners;
+    constructor(opts: HttpTransportOptions);
+    getState(): ConnectionState;
+    listTools(): MCPTool[];
+    onDisconnect(cb: () => void): () => void;
+    onToolsChanged(cb: (tools: MCPTool[]) => void): () => void;
+    /** Refresh tool list when server sends notifications/tools/list_changed. */
+    private handleToolsListChanged;
+    connect(): Promise<void>;
+    private readSSEBody;
+    private buildSSEUrl;
+    private httpPost;
+    callTool(name: string, input: unknown): Promise<ToolCallResult>;
+    close(): Promise<void>;
+}
+/**
+ * Streamable HTTP transport for MCP.
+ *
+ * Uses session-based HTTP with NDJSON responses.
+ */
+declare class StreamableHTTPTransport {
+    private state;
+    private url;
+    private headers;
+    private timeout;
+    private nextId;
+    private tools;
+    private abortController?;
+    private sessionId?;
+    private disconnectHandlers;
+    private readonly toolsChangedListeners;
+    constructor(opts: HttpTransportOptions);
+    getState(): ConnectionState;
+    listTools(): MCPTool[];
+    onDisconnect(cb: () => void): () => void;
+    onToolsChanged(cb: (tools: MCPTool[]) => void): () => void;
+    private handleToolsListChanged;
+    connect(): Promise<void>;
+    private postRaw;
+    callTool(name: string, input: unknown): Promise<ToolCallResult>;
+    close(): Promise<void>;
+}
+
+export { type ConnectionState, type HttpTransportOptions, MCPClient, type MCPClientOptions, MCPRegistry, type MCPRegistryOptions, type MCPTool, SSEReader, SSETransport, StreamableHTTPTransport, type ToolCallResult, type Transport, wrapMCPTool };