atproto-mcp 0.3.0 → 0.4.0

package/README.md

@@ -35,10 +35,13 @@ direct access to the AT Protocol ecosystem, enabling seamless interaction with
 Bluesky and other AT Protocol-based social networks.
 
 **Supports both authenticated and unauthenticated modes** - Start immediately
-with public data access (view profiles, fetch follower/following lists), or add
-authentication for full functionality (search, write operations, private data,
-feeds).
+with public data access (view profiles, search accounts, fetch
+follower/following lists), or add authentication for full functionality (search,
+write operations, private data, feeds).
 
+> **Zero-config launch**: `npx atproto-mcp` runs the server in unauthenticated
+> public-data mode — no credentials required.
+>
 > **Recent additions**: Batch operations for bulk actions, advanced analytics
 > and insights, intelligent content discovery, and a conversation-context
 > scratchpad resource.
@@ -91,22 +94,24 @@ server to access AT Protocol functionality.
 
 ### Core Features
 
-- **Unauthenticated Mode**: Access public data without any setup - view basic
-  profiles and manage OAuth flows
-- **Optional Authentication**: Enable full functionality with app passwords or
-  OAuth for write operations, feeds, and private data
+- **Zero-config Unauthenticated Mode**: Run `npx atproto-mcp` to access public
+  data without any setup - view profiles, search accounts, and fetch
+  follower/following lists
+- **Optional Authentication**: Enable full functionality with app passwords for
+  write operations, feeds, and private data
 - **Complete AT Protocol Integration**: Full implementation using official
   `@atproto/api`
 - **MCP Server Compliance**: Built with `@modelcontextprotocol/sdk` following
   MCP specification
 - **Type-Safe**: Written in TypeScript with strict type checking
-- **Comprehensive Tools**: 60 MCP tools for social networking operations
-- **Real-time Support** _(experimental)_: WebSocket firehose scaffolding with
-  keyword/user buffer scanning — frame decoding is not yet implemented, so no
-  live events are delivered yet
+- **Comprehensive Tools**: 43 MCP tools for social networking operations
 - **Rate Limiting**: Built-in respect for AT Protocol rate limits
 - **Extensible**: Modular architecture for easy customization
 
+> **Planned**: OAuth login and real-time firehose streaming are on the roadmap
+> but not yet functional. App-password authentication is the supported auth path
+> today.
+
 ## Who Is This For?
 
 ### Primary Audience: LLM Clients
@@ -151,14 +156,30 @@ should either:
 
 ## Installation
 
+Run it with no install and no configuration — `npx atproto-mcp` launches the
+server in unauthenticated public-data mode immediately:
+
 ```bash
-npm install -g atproto-mcp
+npx atproto-mcp
 ```
 
-Or use with npx:
+Or install globally:
 
 ```bash
-npx atproto-mcp
+npm install -g atproto-mcp
+```
+
+### Claude Desktop
+
+Add this to your Claude Desktop MCP configuration to run the server with zero
+config:
+
+```json
+{
+  "mcpServers": {
+    "atproto": { "command": "npx", "args": ["-y", "atproto-mcp"] }
+  }
+}
 ```
 
 ## Quick Start
@@ -192,16 +213,18 @@ npx atproto-mcp
 
 - View user profiles (`get_user_profile` - works without auth, provides
   additional viewer-specific data when authenticated)
-- View follower/following lists (`get_followers`, `get_follows` - ENHANCED mode:
-  work without auth, enrich the underlying API call when authenticated)
-- Manage OAuth authentication flows (`start_oauth_flow`,
-  `handle_oauth_callback`, `refresh_oauth_tokens`, `revoke_oauth_tokens`)
+- Search for accounts by handle or name (`search_actors`)
+- List a user's posts (`get_author_feed`)
+- View follower/following lists (`get_user_connections` with
+  `direction: 'followers' | 'follows'` - ENHANCED mode: works without auth,
+  enriches the underlying API call when authenticated)
 
 **Note:** The following features require authentication:
 
 - Searching posts and hashtags (`search_posts`) - **API changed in 2025 to
   require authentication**
-- Browsing feeds and threads (`get_thread`, `get_custom_feed`, `get_timeline`)
+- Browsing feeds and threads (`get_post_context`, `get_custom_feed`,
+  `get_timeline`)
 - All write operations (create, like, repost, follow, etc.)
 - Resources (timeline, profile, notifications) - these are listed but require
   authentication to return data (the `conversation-context` scratchpad resource
@@ -247,7 +270,7 @@ credentials.
 
 ## Available Tools
 
-The server provides **60 MCP tools** across multiple categories. See the
+The server provides **43 MCP tools** across multiple categories. See the
 [complete API documentation](https://cameronrye.github.io/atproto-mcp/api/) for
 detailed information on each tool.
 
@@ -257,34 +280,20 @@ detailed information on each tool.
 
 - `get_user_profile` - Retrieve basic user information (ENHANCED mode: works
   without auth, provides additional viewer-specific data when authenticated)
-- `get_followers` - Get follower lists (ENHANCED mode: works without auth,
-  enriches the underlying API call when authenticated)
-- `get_follows` - Get following lists (ENHANCED mode: works without auth,
+- `get_user_summary` - Get a profile with recent posts and engagement stats in
+  one call (ENHANCED mode)
+- `search_actors` - Find accounts by handle or display name (ENHANCED mode)
+- `get_author_feed` - List a specific user's posts (ENHANCED mode)
+- `get_user_connections` - Get follower or following lists via
+  `direction: 'followers' | 'follows'` (ENHANCED mode: works without auth,
   enriches the underlying API call when authenticated)
+- `get_post_context` - Get a post with optional thread, author profile,
+  engagement metrics, and media (ENHANCED mode)
 
 **Rich Media**
 
-- `generate_alt_text` - Generate descriptive alt text for images (PUBLIC mode:
-  no auth required; experimental — returns an alt-text writing
-  template/guidance, does not analyze image pixels)
 - `analyze_image` - Report blob-declared size and MIME type for an image (PUBLIC
   mode: no auth required; does not decode pixels, so no dimensions/aspect ratio)
-- `extract_media_from_post` - Extract media from posts (ENHANCED mode: works
-  without auth)
-
-**OAuth Management** _(experimental — token exchange not implemented)_
-
-> ⚠️ Only the authorization-URL step is functional. The token-exchange steps
-> (`handle_oauth_callback`, `refresh_oauth_tokens`, `revoke_oauth_tokens`) are
-> **not implemented** and return an error. For working authentication, use app
-> passwords (`ATPROTO_IDENTIFIER` + `ATPROTO_PASSWORD`).
-
-- `start_oauth_flow` - Generate a PKCE authorization URL (experimental)
-- `handle_oauth_callback` - Complete OAuth flow (not implemented — returns
-  error)
-- `refresh_oauth_tokens` - Refresh authentication tokens (not implemented —
-  returns error)
-- `revoke_oauth_tokens` - Revoke OAuth tokens (not implemented — returns error)
 
 **Note:** As of 2025, the AT Protocol API has changed to require authentication
 for most endpoints that were previously public, including `search_posts`.
@@ -293,8 +302,9 @@ for most endpoints that were previously public, including `search_posts`.
 
 **Social Operations**
 
-- `create_post` - Create new posts with rich text support
-- `create_rich_text_post` - Create posts with advanced formatting
+- `create_post` - Create posts with text, auto-detected or explicit richtext
+  facets, replies, image/external embeds, and quote posts
+- `create_thread` - Create multi-post threads in one call
 - `reply_to_post` - Reply to existing posts with threading
 - `like_post` / `unlike_post` - Like and unlike posts
 - `repost` / `unrepost` - Repost content with optional quotes
@@ -304,10 +314,11 @@ for most endpoints that were previously public, including `search_posts`.
 
 - `search_posts` - Search for posts and content across the network (⚠️ API
   changed in 2025 to require auth)
-- `get_thread` - View post threads and conversations
 - `get_custom_feed` - Access custom feeds
 - `get_timeline` - Retrieve personalized timelines
-- `get_notifications` - Access notification feeds
+- `get_notifications` - Access notification feeds (use `countOnly: true` for a
+  cheap unread badge count)
+- `mark_notifications_seen` - Mark notifications as seen up to a timestamp
 
 **Content Management**
 
@@ -327,56 +338,25 @@ for most endpoints that were previously public, including `search_posts`.
 - `mute_user` / `unmute_user` - Mute and unmute users
 - `block_user` / `unblock_user` - Block and unblock users
 - `report_content` / `report_user` - Report content and users
-
-**Real-time Streaming & Intelligence** _(experimental — not yet functional)_
-
-> ⚠️ Firehose frame (CAR/DAG-CBOR) decoding is **not implemented** yet, so these
-> tools currently decode no events: `start_streaming` returns a
-> `not_implemented` status, and the buffer-scanning tools always return empty
-> results. The tool descriptions and responses disclose this. Tracked for a
-> future release.
-
-- `start_streaming` - Start a real-time event stream (returns `not_implemented`)
-- `stop_streaming` - Stop an event stream subscription
-- `get_streaming_status` - Check streaming status (reports decoding
-  availability)
-- `get_recent_events` - Retrieve buffered events (empty until decoding lands)
-- `monitor_keywords` - Scan the event buffer for keywords (empty until decoding
-  lands)
-- `track_users` - Scan the event buffer for specific users (empty until decoding
-  lands)
+- `analyze_moderation_status` - Check moderation status of content
 
 **Batch Operations**
 
-- `batch_follow` - Follow multiple users at once (up to 25)
-- `batch_like` - Like multiple posts at once (up to 25)
-- `batch_repost` - Repost multiple posts at once (up to 25)
+- `batch_action` - Apply one action across up to 25 targets in a single call via
+  `action: 'follow' | 'like' | 'repost'`
 
 **Analytics & Insights**
 
-- `analyze_engagement` - Analyze engagement patterns across posts
-- `analyze_network` - Analyze user's network and connections
-- `suggest_content_strategy` - Get content strategy recommendations based on
-  performance
+- `analyze_account` - Analyze a single account along one dimension via
+  `dimension: 'engagement' | 'network' | 'strategy'`
 - `find_influential_users` - Find influential users in a topic area
 
 **Content Discovery**
 
-- `discover_trending` - Discover trending topics and posts
+- `discover` - Surface timeline content via `mode: 'trending' | 'recommended'`
 - `find_similar_users` - Find users similar to a given user
-- `recommend_content` - Get personalized content recommendations
 - `discover_communities` - Discover communities around topics
 
-**Composite Operations**
-
-- `get_user_summary` - Get complete user profile with stats and analysis
-- `get_post_context` - Get post with thread, author, and engagement data
-- `create_thread` - Create multi-post threads in one call
-
-**Enhanced Moderation**
-
-- `analyze_moderation_status` - Check moderation status of content
-
 ## Documentation
 
 Visit our [documentation site](https://cameronrye.github.io/atproto-mcp) for:
@@ -400,17 +380,8 @@ export ATPROTO_PASSWORD="your-app-password"
 atproto-mcp
 ```
 
-### OAuth (experimental — not yet functional)
-
-> ⚠️ OAuth token exchange is not implemented, so this cannot complete a login
-> yet. App passwords (above) are the recommended/working method. The variables
-> below configure the experimental authorization-URL generator.
-
-```bash
-export ATPROTO_CLIENT_ID="your-client-id"
-export ATPROTO_CLIENT_SECRET="your-client-secret"  # optional for public clients
-atproto-mcp --auth oauth
-```
+App passwords are the supported authentication path. OAuth login is planned but
+not yet functional.
 
 ## Development
 
@@ -508,8 +479,9 @@ npm run test:integration
 
 **What's tested:**
 
-- Public/enhanced tools (`get_user_profile`, `get_followers`, `get_follows`) and
-  authenticated tools (`search_posts`, `get_thread`, `get_custom_feed`)
+- Public/enhanced tools (`get_user_profile`, `get_user_connections`,
+  `get_author_feed`) and authenticated tools (`search_posts`,
+  `get_post_context`, `get_custom_feed`)
 - DID and handle resolution
 - Pagination support
 - Error handling

package/dist/index.d.ts

@@ -36,6 +36,12 @@ export declare class AtpMcpServer {
      * Register MCP tools with the server
      */
     private registerTools;
+    /**
+     * Normalize an error thrown inside a resource/prompt handler into an McpError:
+     * pass an existing McpError through, otherwise log + sanitize and wrap it as an
+     * InternalError. Returned (not thrown) so the caller writes `throw this.…`.
+     */
+    private toHandlerMcpError;
     /**
      * Register MCP resources with the server
      */

package/dist/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":";AAEA;;;;;;GAMG;AAEH,OAAO,EAAE,MAAM,EAAE,MAAM,2CAA2C,CAAC;AAKnE,OAAO,EAAsB,KAAK,gBAAgB,EAAmB,MAAM,kBAAkB,CAAC;AAC9F,OAAO,EAAE,SAAS,EAAE,MAAM,uBAAuB,CAAC;AAElD,OAAO,EAAE,aAAa,EAAE,MAAM,mBAAmB,CAAC;AAKlD,OAAO,EAAE,KAAK,mBAAmB,EAAsB,MAAM,wBAAwB,CAAC;AACtF,OAAO,EAAwB,eAAe,EAAE,MAAM,qBAAqB,CAAC;AAE5E;;GAEG;AACH,qBAAa,YAAY;IACvB,OAAO,CAAC,MAAM,CAAS;IACvB,OAAO,CAAC,SAAS,CAAY;IAC7B,OAAO,CAAC,MAAM,CAAS;IACvB,OAAO,CAAC,aAAa,CAAgB;IACrC,OAAO,CAAC,kBAAkB,CAAqB;IAC/C,OAAO,CAAC,eAAe,CAAkB;IACzC,OAAO,CAAC,eAAe,CAAC,CAAiB;IACzC,OAAO,CAAC,SAAS,CAAqC;IACtD,OAAO,CAAC,SAAS,CAAS;IAC1B,OAAO,CAAC,cAAc,CAAS;gBAEnB,eAAe,GAAE,OAAO,CAAC,gBAAgB,CAAM;IAsD3D;;;OAGG;IACH,OAAO,CAAC,WAAW;IAwBnB;;OAEG;IACH,OAAO,CAAC,aAAa;IA4JrB;;OAEG;IACH,OAAO,CAAC,iBAAiB;IA2EzB;;OAEG;IACH,OAAO,CAAC,eAAe;IAiEvB;;;;;OAKG;IACH,OAAO,CAAC,eAAe;IAWvB;;OAEG;IACU,KAAK,IAAI,OAAO,CAAC,IAAI,CAAC;IA6EnC;;OAEG;IACU,IAAI,IAAI,OAAO,CAAC,IAAI,CAAC;IAUlC;;OAEG;YACW,OAAO;IAqDrB;;OAEG;IACI,SAAS,IAAI;QAClB,SAAS,EAAE,OAAO,CAAC;QACnB,eAAe,EAAE,OAAO,CAAC;QACzB,QAAQ,EAAE,iBAAiB,GAAG,cAAc,GAAG,OAAO,CAAC;QACvD,iBAAiB,EAAE,OAAO,CAAC;QAC3B,MAAM,EAAE,gBAAgB,CAAC;KAC1B;IAUD;;OAEG;IACI,YAAY,IAAI,SAAS;IAIhC;;;;;OAKG;IACI,SAAS,IAAI,MAAM;IAI1B;;OAEG;IACI,gBAAgB,IAAI,aAAa;IAIxC;;OAEG;IACI,qBAAqB,IAAI,mBAAmB;IAInD;;OAEG;IACI,kBAAkB,IAAI,eAAe;IAI5C;;OAEG;IACI,gBAAgB,IAAI;QACzB,WAAW,EAAE,mBAAmB,CAAC;QACjC,QAAQ,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;QAClC,MAAM,EAAE;YACN,SAAS,EAAE,OAAO,CAAC;YACnB,eAAe,EAAE,OAAO,CAAC;YACzB,QAAQ,EAAE,iBAAiB,GAAG,cAAc,GAAG,OAAO,CAAC;YACvD,iBAAiB,EAAE,OAAO,CAAC;YAC3B,MAAM,EAAE,gBAAgB,CAAC;SAC1B,CAAC;KACH;CAOF;AAED;;;;;;;;;;;;GAYG;AACH,eAAe,YAAY,CAAC"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":";AAEA;;;;;;GAMG;AAEH,OAAO,EAAE,MAAM,EAAE,MAAM,2CAA2C,CAAC;AAKnE,OAAO,EAAsB,KAAK,gBAAgB,EAAmB,MAAM,kBAAkB,CAAC;AAC9F,OAAO,EAAE,SAAS,EAAE,MAAM,uBAAuB,CAAC;AAElD,OAAO,EAAE,aAAa,EAAE,MAAM,mBAAmB,CAAC;AAIlD,OAAO,EAAE,KAAK,mBAAmB,EAAsB,MAAM,wBAAwB,CAAC;AACtF,OAAO,EAAwB,eAAe,EAAE,MAAM,qBAAqB,CAAC;AA4D5E;;GAEG;AACH,qBAAa,YAAY;IACvB,OAAO,CAAC,MAAM,CAAS;IACvB,OAAO,CAAC,SAAS,CAAY;IAC7B,OAAO,CAAC,MAAM,CAAS;IACvB,OAAO,CAAC,aAAa,CAAgB;IACrC,OAAO,CAAC,kBAAkB,CAAqB;IAC/C,OAAO,CAAC,eAAe,CAAkB;IACzC,OAAO,CAAC,eAAe,CAAC,CAAiB;IACzC,OAAO,CAAC,SAAS,CAAqC;IACtD,OAAO,CAAC,SAAS,CAAS;IAC1B,OAAO,CAAC,cAAc,CAAS;gBAEnB,eAAe,GAAE,OAAO,CAAC,gBAAgB,CAAM;IA0D3D;;;OAGG;IACH,OAAO,CAAC,WAAW;IAwBnB;;OAEG;IACH,OAAO,CAAC,aAAa;IAmJrB;;;;OAIG;IACH,OAAO,CAAC,iBAAiB;IAezB;;OAEG;IACH,OAAO,CAAC,iBAAiB;IAgEzB;;OAEG;IACH,OAAO,CAAC,eAAe;IAwDvB;;;;;OAKG;IACH,OAAO,CAAC,eAAe;IAWvB;;OAEG;IACU,KAAK,IAAI,OAAO,CAAC,IAAI,CAAC;IA6EnC;;OAEG;IACU,IAAI,IAAI,OAAO,CAAC,IAAI,CAAC;IAUlC;;OAEG;YACW,OAAO;IAiDrB;;OAEG;IACI,SAAS,IAAI;QAClB,SAAS,EAAE,OAAO,CAAC;QACnB,eAAe,EAAE,OAAO,CAAC;QACzB,QAAQ,EAAE,iBAAiB,GAAG,cAAc,GAAG,OAAO,CAAC;QACvD,iBAAiB,EAAE,OAAO,CAAC;QAC3B,MAAM,EAAE,gBAAgB,CAAC;KAC1B;IAUD;;OAEG;IACI,YAAY,IAAI,SAAS;IAIhC;;;;;OAKG;IACI,SAAS,IAAI,MAAM;IAI1B;;OAEG;IACI,gBAAgB,IAAI,aAAa;IAIxC;;OAEG;IACI,qBAAqB,IAAI,mBAAmB;IAInD;;OAEG;IACI,kBAAkB,IAAI,eAAe;IAI5C;;OAEG;IACI,gBAAgB,IAAI;QACzB,WAAW,EAAE,mBAAmB,CAAC;QACjC,QAAQ,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;QAClC,MAAM,EAAE;YACN,SAAS,EAAE,OAAO,CAAC;YACnB,eAAe,EAAE,OAAO,CAAC;YACzB,QAAQ,EAAE,iBAAiB,GAAG,cAAc,GAAG,OAAO,CAAC;YACvD,iBAAiB,EAAE,OAAO,CAAC;YAC3B,MAAM,EAAE,gBAAgB,CAAC;SAC1B,CAAC;KACH;CAOF;AAED;;;;;;;;;;;;GAYG;AACH,eAAe,YAAY,CAAC"}

package/dist/index.js

@@ -16,11 +16,65 @@ import { AtpClient } from './utils/atp-client.js';
 import { Logger } from './utils/logger.js';
 import { ConfigManager } from './utils/config.js';
 import { createTools } from './tools/index.js';
-import { StartStreamingTool } from './tools/implementations/streaming-tools.js';
 import { createResources } from './resources/index.js';
 import { createPrompts } from './prompts/index.js';
 import { PerformanceMonitor } from './utils/performance.js';
 import { SecurityManager } from './utils/security.js';
+/**
+ * Pure read tools (no writes to the network). readOnlyHint:true lets clients
+ * auto-approve them. Curated explicitly per tool — NOT derived from auth mode,
+ * which encodes auth requirement, not destructiveness.
+ */
+const READ_ONLY_TOOLS = new Set([
+    'analyze_account',
+    'analyze_image',
+    'analyze_moderation_status',
+    'discover',
+    'discover_communities',
+    'find_influential_users',
+    'find_similar_users',
+    'generate_link_preview',
+    'get_author_feed',
+    'get_custom_feed',
+    'get_list',
+    'get_notifications',
+    'get_post_context',
+    'get_timeline',
+    'get_user_connections',
+    'get_user_profile',
+    'get_user_summary',
+    'search_actors',
+    'search_posts',
+]);
+/**
+ * Tools whose effect is irreversible or removes/limits data (deletes, blocks,
+ * mutes, reports, removals, token revocation). destructiveHint:true lets clients
+ * surface confirmation UI and withhold auto-approval.
+ */
+const DESTRUCTIVE_TOOLS = new Set([
+    'block_user',
+    'delete_post',
+    'mute_user',
+    'remove_from_list',
+    'report_content',
+    'report_user',
+    'unfollow_user',
+    'unlike_post',
+    'unrepost',
+]);
+/**
+ * Build the advertised annotations for a tool. openWorldHint is true for every
+ * tool (they all reach a live network). A per-tool `schema.annotations` override
+ * wins over these defaults.
+ */
+function computeToolAnnotations(method, override) {
+    return {
+        openWorldHint: true,
+        ...(READ_ONLY_TOOLS.has(method) ? { readOnlyHint: true } : {}),
+        ...(DESTRUCTIVE_TOOLS.has(method) ? { destructiveHint: true } : {}),
+        ...(override ?? {}),
+    };
+}
 /**
  * Main server class for AT Protocol MCP Server
  */
@@ -58,7 +112,11 @@ export class AtpMcpServer {
             this.performanceMonitor = new PerformanceMonitor(this.logger);
             // Initialize security manager
             const securityConfig = {
-                enableInputSanitization: true,
+                // The blanket HTML/script InputSanitizer is intentionally NOT applied to
+                // tool arguments (it would corrupt legitimate post content). Per-field
+                // zod validation and url-safety guards are the real defenses, so this flag
+                // honestly reports that the object sanitizer does not run on the hot path.
+                enableInputSanitization: false,
                 enableRateLimit: true,
                 enableErrorSanitization: true,
                 maxInputLength: 10000,
@@ -118,6 +176,12 @@ export class AtpMcpServer {
                 inputSchema: tool.schema.params
                     ? this.zodToJsonSchema(tool.schema.params)
                     : { type: 'object', properties: {} },
+                // Advertise an output schema when the tool declares one. This is purely
+                // descriptive metadata in the tools/list payload; because tools/call
+                // responses are built by this custom handler (not the SDK's high-level
+                // registerTool), it does not trigger structuredContent validation.
+                ...(tool.schema.outputSchema ? { outputSchema: tool.schema.outputSchema } : {}),
+                annotations: computeToolAnnotations(tool.schema.method, tool.schema.annotations),
             })),
         }));
         // Build a name -> tool lookup so a SINGLE tools/call handler can dispatch
@@ -144,6 +208,17 @@ export class AtpMcpServer {
                     tool: toolName,
                 });
             }
+            // Build an MCP "tool error" result. Per the MCP spec, errors that occur
+            // while a (known) tool runs — including invalid arguments, unavailable
+            // tools, and rate limiting — are reported as a result with isError: true,
+            // NOT as JSON-RPC protocol errors. This lets the calling model SEE the
+            // error text and react (fix arguments, authenticate, back off) instead of
+            // receiving an opaque transport failure. Protocol errors are reserved for
+            // problems with the request itself (e.g. an unknown tool, handled above).
+            const toolError = (message) => ({
+                content: [{ type: 'text', text: message }],
+                isError: true,
+            });
             // Rate-limit tool invocations to guard against runaway loops / abuse.
             // Note: tool arguments are intentionally NOT passed through the HTML/script
             // input sanitizer — that sanitizer strips characters (`<`, `>`, collapses
@@ -151,51 +226,38 @@ export class AtpMcpServer {
             // data. Per-field validation is handled by each tool's zod schema, and
             // outbound URLs/paths are guarded at their call sites (see url-safety).
             if (!this.securityManager.checkRateLimit(`tool:${toolName}`)) {
-                throw new McpError(ErrorCode.InternalError, `Rate limit exceeded for tool "${toolName}". Please slow down and retry shortly.`, { tool: toolName });
+                return toolError(`Rate limit exceeded for tool "${toolName}". Please slow down and retry shortly.`);
+            }
+            // Surface tool availability (e.g. requires authentication) as a result the
+            // model can act on, not a protocol error.
+            if ('isAvailable' in tool &&
+                typeof tool.isAvailable === 'function' &&
+                !tool.isAvailable()) {
+                const availabilityMessage = 'getAvailabilityMessage' in tool && typeof tool.getAvailabilityMessage === 'function'
+                    ? tool.getAvailabilityMessage()
+                    : 'Tool not available';
+                return toolError(`Tool not available: ${availabilityMessage}`);
             }
             try {
-                // Check if tool is available before execution
-                if ('isAvailable' in tool && typeof tool.isAvailable === 'function') {
-                    if (!tool.isAvailable()) {
-                        const availabilityMessage = 'getAvailabilityMessage' in tool &&
-                            typeof tool.getAvailabilityMessage === 'function'
-                            ? tool.getAvailabilityMessage()
-                            : 'Tool not available';
-                        throw new McpError(ErrorCode.InternalError, `Tool not available: ${availabilityMessage}`, {
-                            tool: toolName,
-                            availability: availabilityMessage,
-                        });
-                    }
-                }
                 const result = await tool.handler(request.params.arguments || {});
-                // DESIGN DECISION: Return results as formatted JSON text for LLM consumption
-                //
-                // This server intentionally returns all tool results as stringified JSON text
-                // rather than using MCP's structured content types. This is a deliberate
-                // architectural choice with the following rationale:
-                //
-                // 1. Consistency: All tools return the same format, making it easier for LLMs
-                //    to parse and understand responses without needing to handle multiple
-                //    content type variations.
+                // Return BOTH representations:
                 //
-                // 2. Readability: Pretty-printed JSON (with 2-space indentation) is optimized
-                //    for LLM token processing and human readability during debugging.
+                // - content[].text: pretty-printed JSON, optimized for LLM consumption.
+                //   LLMs parse formatted JSON text effectively and it is universally
+                //   supported across all MCP clients, so it stays the primary channel.
                 //
-                // 3. Compatibility: Text content is universally supported across all MCP clients,
-                //    ensuring maximum compatibility without client-specific handling.
+                // - structuredContent: the same result as a machine-readable object, for
+                //   non-LLM consumers and tool-chaining clients that would otherwise have
+                //   to re-parse the pretty-printed string. SDK structuredContent must be a
+                //   JSON object, so bare arrays/primitives are wrapped under `result`.
                 //
-                // 4. Debugging: Formatted JSON makes it easier to debug and inspect responses
-                //    in logs and during development.
-                //
-                // 5. LLM Processing: LLMs are highly effective at parsing JSON text and can
-                //    extract structured information from formatted JSON strings.
-                //
-                // Alternative Approach: MCP supports structured content types (e.g., JSON objects,
-                // arrays, etc.) which could be used instead. However, testing has shown that
-                // stringified JSON provides better results for LLM clients in practice.
-                //
-                // If you need structured content types for programmatic processing, consider
-                // parsing the JSON text in your client application.
+                // NOTE: we intentionally do NOT declare per-tool `outputSchema` — doing so
+                // makes the SDK REQUIRE and validate structuredContent on every call and
+                // throw on any non-conforming object. structuredContent here is additive
+                // and best-effort.
+                const structuredContent = result != null && typeof result === 'object' && !Array.isArray(result)
+                    ? result
+                    : { result };
                 return {
                     content: [
                         {
@@ -203,31 +265,39 @@ export class AtpMcpServer {
                             text: JSON.stringify(result, null, 2),
                         },
                     ],
+                    structuredContent,
                 };
             }
             catch (error) {
                 this.logger.error(`Tool ${toolName} execution failed`, error);
-                // Re-throw protocol errors (unknown/unavailable tool) as-is so the
-                // client receives the accurate JSON-RPC code.
-                if (error instanceof McpError) {
-                    throw error;
-                }
-                // Invalid input is a client-correctable condition: map it to the
-                // spec's InvalidParams (-32602) rather than InternalError (-32603).
+                // Invalid arguments are safe to surface verbatim so the model can fix them.
                 if (error instanceof ValidationError) {
-                    throw new McpError(ErrorCode.InvalidParams, error.message, { tool: toolName });
+                    return toolError(`Invalid parameters: ${error.message}`);
                 }
                 // Sanitize internal error details before returning to the client.
                 const sanitized = this.securityManager
                     .getErrorSanitizer()
                     .sanitizeError(error instanceof Error ? error : new Error(String(error)));
-                throw new McpError(ErrorCode.InternalError, `Tool execution failed: ${sanitized.message}`, {
-                    tool: toolName,
-                });
+                return toolError(`Tool execution failed: ${sanitized.message}`);
             }
         });
         this.logger.info(`Registered ${tools.length} MCP tools`);
     }
+    /**
+     * Normalize an error thrown inside a resource/prompt handler into an McpError:
+     * pass an existing McpError through, otherwise log + sanitize and wrap it as an
+     * InternalError. Returned (not thrown) so the caller writes `throw this.…`.
+     */
+    toHandlerMcpError(error, label, context) {
+        this.logger.error(label, error);
+        if (error instanceof McpError) {
+            return error;
+        }
+        const sanitized = this.securityManager
+            .getErrorSanitizer()
+            .sanitizeError(error instanceof Error ? error : new Error(String(error)));
+        return new McpError(ErrorCode.InternalError, `${label}: ${sanitized.message}`, context);
+    }
     /**
      * Register MCP resources with the server
      */
@@ -272,14 +342,7 @@ export class AtpMcpServer {
                 };
             }
             catch (error) {
-                this.logger.error(`Resource read failed`, error);
-                if (error instanceof McpError) {
-                    throw error;
-                }
-                const sanitized = this.securityManager
-                    .getErrorSanitizer()
-                    .sanitizeError(error instanceof Error ? error : new Error(String(error)));
-                throw new McpError(ErrorCode.InternalError, `Resource read failed: ${sanitized.message}`, {
+                throw this.toHandlerMcpError(error, 'Resource read failed', {
                     uri: request.params.uri,
                 });
             }
@@ -322,14 +385,9 @@ export class AtpMcpServer {
                 return { messages };
             }
             catch (error) {
-                this.logger.error(`Prompt generation failed`, error);
-                if (error instanceof McpError) {
-                    throw error;
-                }
-                const sanitized = this.securityManager
-                    .getErrorSanitizer()
-                    .sanitizeError(error instanceof Error ? error : new Error(String(error)));
-                throw new McpError(ErrorCode.InternalError, `Prompt generation failed: ${sanitized.message}`, { name: request.params.name });
+                throw this.toHandlerMcpError(error, 'Prompt generation failed', {
+                    name: request.params.name,
+                });
             }
         });
         this.logger.info(`Registered ${prompts.length} MCP prompts`);
@@ -446,9 +504,6 @@ export class AtpMcpServer {
             }
             // Release security manager background timers (rate-limiter cleanup).
             this.securityManager.destroy();
-            // Disconnect the shared firehose client (if a streaming tool opened one)
-            // so its socket and heartbeat timer do not outlive the server.
-            await StartStreamingTool.shutdown();
         }
         catch (error) {
             errors.push(error instanceof Error ? error : new Error(String(error)));