atproto-mcp 0.4.0 → 0.6.0

package/README.md

@@ -42,9 +42,9 @@ 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.
+> **Recent additions**: Bluesky direct messages, private bookmarks, starter pack
+> discovery, reply/quote controls on posts, parameterized MCP resource
+> templates, and an optional Streamable HTTP transport (`--transport http`).
 
 ## Architecture
 
@@ -87,10 +87,11 @@ server to access AT Protocol functionality.
   (follow/like/repost up to 25 items at once)
 - **Analytics & Insights**: Analyze engagement patterns, network connections,
   and get content strategy recommendations
-- **Content Discovery**: Find similar users, trending topics, and influential
-  voices in your areas of interest
-- **Conversation Context**: An MCP resource that acts as a scratchpad for
-  conversation state (not auto-populated yet)
+- **Content Discovery**: Find similar users, trending topics, starter packs, and
+  influential voices in your areas of interest
+- **Direct Messages**: List conversations, read message history, and send
+  Bluesky DMs (requires a DM-enabled app password)
+- **Private Bookmarks**: Save, list, and remove private bookmarks on posts
 
 ### Core Features
 
@@ -104,13 +105,16 @@ server to access AT Protocol functionality.
 - **MCP Server Compliance**: Built with `@modelcontextprotocol/sdk` following
   MCP specification
 - **Type-Safe**: Written in TypeScript with strict type checking
-- **Comprehensive Tools**: 43 MCP tools for social networking operations
+- **Comprehensive Tools**: 51 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.
+> **Planned**: OAuth login is on the roadmap but not yet functional —
+> app-password authentication is the supported auth path today. Real-time
+> firehose streaming is **not** planned as MCP tools: a request/response tool
+> cannot honestly expose a continuous stream, and the unused firehose client
+> code has been removed. If streaming ever ships it will be built fresh on
+> [Jetstream](https://docs.bsky.app/blog/jetstream).
 
 ## Who Is This For?
 
@@ -227,10 +231,10 @@ config:
   `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
-  is readable without auth and simply returns near-empty placeholder content)
-- Prompts (content composition, reply templates) - these are listed but require
-  authentication to be available
+  authentication to return data
+
+Prompts (content composition, reply templates) are pure text templates and work
+without authentication.
 
 **Important:** All tools, resources, and prompts are listed by the MCP server
 regardless of authentication state. Most tools and resources that require
@@ -270,7 +274,7 @@ credentials.
 
 ## Available Tools
 
-The server provides **43 MCP tools** across multiple categories. See the
+The server provides **51 MCP tools** across multiple categories. See the
 [complete API documentation](https://cameronrye.github.io/atproto-mcp/api/) for
 detailed information on each tool.
 
@@ -289,6 +293,8 @@ detailed information on each tool.
   enriches the underlying API call when authenticated)
 - `get_post_context` - Get a post with optional thread, author profile,
   engagement metrics, and media (ENHANCED mode)
+- `search_starter_packs` / `get_starter_pack` - Search Bluesky starter packs by
+  keyword and fetch a pack's details (ENHANCED mode)
 
 **Rich Media**
 
@@ -320,6 +326,18 @@ for most endpoints that were previously public, including `search_posts`.
   cheap unread badge count)
 - `mark_notifications_seen` - Mark notifications as seen up to a timestamp
 
+**Direct Messages**
+
+- `list_conversations` - List your Bluesky DM conversations
+- `get_conversation_messages` - Read a conversation's message history
+- `send_direct_message` - Send a DM (requires an app password created with
+  "Allow access to your direct messages" enabled)
+
+**Bookmarks**
+
+- `add_bookmark` / `remove_bookmark` - Privately bookmark and un-bookmark posts
+- `get_bookmarks` - List your private bookmarks
+
 **Content Management**
 
 - `upload_image` / `upload_video` - Upload media content
@@ -524,10 +542,13 @@ This project is licensed under the MIT License.
 
 ## Deployment
 
-This is a **stdio MCP server**: it is normally launched by an MCP client (e.g.
-Claude Desktop) via `npx atproto-mcp` and communicates over stdin/stdout. It
-does not listen on a network port, so there is no HTTP endpoint to expose or
-scale.
+By default this is a **stdio MCP server**: it is normally launched by an MCP
+client (e.g. Claude Desktop) via `npx atproto-mcp` and communicates over
+stdin/stdout, binding no network port. Alternatively, `--transport http` serves
+the MCP **Streamable HTTP** transport at `http://<host>:<port>/mcp` (default
+binding `127.0.0.1:3000`, loopback only); exposing it beyond loopback (e.g.
+`--host 0.0.0.0`) is the operator's responsibility to secure. stdio remains the
+default and the recommended setup for MCP clients.
 
 ### Built-in safeguards
 

package/dist/cli.d.ts

@@ -2,9 +2,32 @@
 /**
  * Command-line interface for the AT Protocol MCP Server
  */
+import { type IMcpServerConfig } from './types/index.js';
+import { type McpTransportKind } from './index.js';
+/**
+ * Result of CLI argument parsing: configuration overrides plus the selected
+ * transport. The transport is deliberately NOT part of IMcpServerConfig — it
+ * is a process-level startup choice, passed to AtpMcpServer.start().
+ */
+export interface ICliArgs {
+    config: Partial<IMcpServerConfig>;
+    transport: McpTransportKind;
+}
+/**
+ * Parse command line arguments. `argv` defaults to the process arguments and
+ * is injectable for tests.
+ */
+export declare function parseCliArgs(argv?: string[]): ICliArgs;
 /**
  * Main CLI function
  */
 declare function main(): Promise<void>;
+/**
+ * Detect whether a module is the process entry point. Node realpath-resolves
+ * import.meta.url for the main module, but argv[1] stays the literal invoked
+ * path — and npm installs bins as symlinks — so a naive string comparison
+ * against `file://${argv[1]}` breaks symlinked, relative, and space-containing
+ * paths. Compare realpath-resolved file URLs instead.
+ */
+export declare function isMainModule(importMetaUrl: string, argv1: string | undefined): boolean;
 export { main as runCli };
-//# sourceMappingURL=cli.d.ts.map

package/dist/cli.js

@@ -3,9 +3,9 @@
  * Command-line interface for the AT Protocol MCP Server
  */
 import { parseArgs } from 'node:util';
-import { existsSync, readFileSync } from 'node:fs';
+import { existsSync, readFileSync, realpathSync } from 'node:fs';
 import { dirname, join } from 'node:path';
-import { fileURLToPath } from 'node:url';
+import { fileURLToPath, pathToFileURL } from 'node:url';
 import { ConfigurationError } from './types/index.js';
 import { AtpMcpServer } from './index.js';
 import { LogLevel, Logger } from './utils/logger.js';
@@ -66,6 +66,11 @@ function loadEnvFile() {
  * CLI argument definitions
  */
 const CLI_OPTIONS = {
+    transport: {
+        type: 'string',
+        short: 't',
+        description: 'Transport: stdio|http (default: stdio)',
+    },
     port: {
         type: 'string',
         short: 'p',
@@ -73,7 +78,7 @@ const CLI_OPTIONS = {
     },
     host: {
         type: 'string',
-        short: 'h',
+        short: 'H',
         description: 'Server host (default: localhost)',
     },
     service: {
@@ -93,6 +98,7 @@ const CLI_OPTIONS = {
     },
     help: {
         type: 'boolean',
+        short: 'h',
         description: 'Show help message',
     },
     version: {
@@ -112,17 +118,22 @@ AT Protocol MCP Server - Comprehensive interface for LLMs to interact with AT Pr
 
 Usage: atproto-mcp [options]
 
-Transport: this server communicates over stdio (for MCP clients such as Claude
-Desktop). It does not listen on a TCP port; --port/--host are accepted but
-currently have no effect.
+Transport: by default this server communicates over stdio (for MCP clients
+such as Claude Desktop). With --transport http it serves the MCP Streamable
+HTTP transport at http://<host>:<port>/mcp instead. The default binding is the
+loopback interface (127.0.0.1), so only local clients can connect; binding any
+other host (e.g. --host 0.0.0.0) exposes the server to the network, and
+securing that exposure (firewalling, reverse proxy, authentication) is the
+operator's responsibility.
 
 Options:
-  -p, --port <number>        Server port (reserved; stdio transport ignores it)
-  -h, --host <string>        Server host (reserved; stdio transport ignores it)
+  -t, --transport <mode>     Transport: stdio|http (default: stdio)
+  -p, --port <number>        HTTP port for --transport http (default: 3000; stdio ignores it)
+  -H, --host <string>        HTTP bind host for --transport http (default: 127.0.0.1, loopback; stdio ignores it)
   -s, --service <url>        AT Protocol service URL (default: https://bsky.social)
   -a, --auth <method>        Authentication method: app-password|oauth (optional)
   -l, --log-level <level>    Log level: debug|info|warn|error (default: info)
-      --help                 Show this help message
+  -h, --help                 Show this help message
   -v, --version              Show version information
 
 🔓 Unauthenticated Mode (Default):
@@ -154,8 +165,8 @@ Examples:
   # Start in unauthenticated mode (works immediately!)
   atproto-mcp
 
-  # Start with custom port and debug logging
-  atproto-mcp --port 8080 --log-level debug
+  # Serve the Streamable HTTP transport on loopback port 8080
+  atproto-mcp --transport http --port 8080 --log-level debug
 
   # Enable authentication with app password
   export ATPROTO_IDENTIFIER="your-handle.bsky.social"
@@ -184,11 +195,13 @@ function showVersion() {
     }
 }
 /**
- * Parse command line arguments
+ * Parse command line arguments. `argv` defaults to the process arguments and
+ * is injectable for tests.
  */
-function parseCliArgs() {
+export function parseCliArgs(argv = process.argv.slice(2)) {
     try {
         const { values } = parseArgs({
+            args: argv,
             options: CLI_OPTIONS,
             allowPositionals: false,
         });
@@ -211,6 +224,15 @@ function parseCliArgs() {
                 throw new ConfigurationError(`Invalid log level: ${values['log-level']}. Must be one of: debug, info, warn, error`);
             }
         }
+        // Validate the transport selection. stdio stays the default; http serves
+        // the Streamable HTTP transport using the --port/--host binding.
+        let transport = 'stdio';
+        if (values.transport != null && values.transport !== '') {
+            if (values.transport !== 'stdio' && values.transport !== 'http') {
+                throw new ConfigurationError(`Invalid transport: ${values.transport}. Must be 'stdio' or 'http'`);
+            }
+            transport = values.transport;
+        }
         // Build configuration from CLI arguments
         const config = {};
         if (values.port != null && values.port !== '') {
@@ -246,7 +268,7 @@ function parseCliArgs() {
             }
             config.atproto = atproto;
         }
-        return config;
+        return { config, transport };
     }
     catch (error) {
         if (error instanceof ConfigurationError) {
@@ -266,7 +288,7 @@ async function main() {
         // visible to ConfigManager and the rest of the server.
         loadEnvFile();
         // Parse command line arguments
-        const cliConfig = parseCliArgs();
+        const { config: cliConfig, transport } = parseCliArgs();
         // Create and start server
         const server = new AtpMcpServer(cliConfig);
         // Setup graceful shutdown handlers
@@ -297,7 +319,7 @@ async function main() {
             process.exit(1);
         });
         // Start the server
-        await server.start();
+        await server.start({ transport });
         // Keep the process running
         logger.info('AT Protocol MCP Server is running. Press Ctrl+C to stop.');
     }
@@ -311,12 +333,29 @@ async function main() {
         process.exit(1);
     }
 }
+/**
+ * Detect whether a module is the process entry point. Node realpath-resolves
+ * import.meta.url for the main module, but argv[1] stays the literal invoked
+ * path — and npm installs bins as symlinks — so a naive string comparison
+ * against `file://${argv[1]}` breaks symlinked, relative, and space-containing
+ * paths. Compare realpath-resolved file URLs instead.
+ */
+export function isMainModule(importMetaUrl, argv1) {
+    if (argv1 == null || argv1 === '') {
+        return false;
+    }
+    try {
+        return importMetaUrl === pathToFileURL(realpathSync(argv1)).href;
+    }
+    catch {
+        return false;
+    }
+}
 // Run CLI if this file is executed directly
-if (import.meta.url === `file://${process.argv[1]}`) {
+if (isMainModule(import.meta.url, process.argv[1])) {
     main().catch(error => {
         console.error('Fatal error:', error);
         process.exit(1);
     });
 }
 export { main as runCli };
-//# sourceMappingURL=cli.js.map

package/dist/health-check.d.ts

@@ -11,4 +11,3 @@
  * and reporting them would be misleading.
  */
 export {};
-//# sourceMappingURL=health-check.d.ts.map

package/dist/health-check.js

@@ -10,6 +10,7 @@
  * connection counts of the running server — a fresh process cannot observe those
  * and reporting them would be misleading.
  */
+import { isMainModule } from './cli.js';
 import { AtpMcpServer } from './index.js';
 function healthCheck() {
     try {
@@ -47,7 +48,6 @@ function healthCheck() {
     }
 }
 // Run health check if this script is executed directly
-if (import.meta.url === `file://${process.argv[1]}`) {
+if (isMainModule(import.meta.url, process.argv[1])) {
     void healthCheck();
 }
-//# sourceMappingURL=health-check.js.map

package/dist/index.d.ts

@@ -12,6 +12,23 @@ import { AtpClient } from './utils/atp-client.js';
 import { ConfigManager } from './utils/config.js';
 import { type IPerformanceMetrics } from './utils/performance.js';
 import { SecurityManager } from './utils/security.js';
+/**
+ * Transports the server can speak. stdio is the default (MCP clients such as
+ * Claude Desktop spawn the process and own its stdin/stdout); http serves the
+ * MCP Streamable HTTP transport on a TCP port at /mcp.
+ */
+export type McpTransportKind = 'stdio' | 'http';
+/**
+ * Options for {@link AtpMcpServer.start}. port/host apply to the http
+ * transport only and override the configured values (config.port/config.host),
+ * which lets tests bind an ephemeral port (0) that the config schema does not
+ * allow.
+ */
+export interface IServerStartOptions {
+    transport?: McpTransportKind;
+    port?: number;
+    host?: string;
+}
 /**
  * Main server class for AT Protocol MCP Server
  */
@@ -24,9 +41,21 @@ export declare class AtpMcpServer {
     private securityManager;
     private metricsInterval?;
     private transport;
+    private httpServer;
+    private httpSessions;
+    private httpAllowedHosts;
     private isRunning;
     private isShuttingDown;
     constructor(configOverrides?: Partial<IMcpServerConfig>);
+    /**
+     * Construct an MCP Server instance with every handler registered.
+     *
+     * This is the single construction path for ALL transports: the constructor
+     * builds the stdio server through it, and the http transport builds one
+     * fresh Server per session through it (each Streamable HTTP session needs
+     * its own Server because the SDK Protocol binds 1:1 to a transport).
+     */
+    private createMcpServer;
     /**
      * Set up the MCP server with basic handlers
      * Register tools, resources, and prompts with the MCP server
@@ -50,6 +79,18 @@ export declare class AtpMcpServer {
      * Register MCP prompts with the server
      */
     private registerPrompts;
+    /**
+     * Register the completion/complete handler (declared via the `completions`
+     * capability).
+     *
+     * - ref/prompt: serves candidate values for enumerable prompt arguments
+     *   (each prompt declares its own candidates); free-text arguments complete
+     *   to an empty list, never an error. Unknown prompt names are invalid params.
+     * - ref/resource: serves the {actor} variable of the resource templates with
+     *   the authenticated user's handle when a session exists, else empty.
+     *   Unknown templates/arguments complete to an empty list.
+     */
+    private registerCompletions;
     /**
      * Convert Zod schema to JSON Schema for MCP compatibility
      *
@@ -58,9 +99,59 @@ export declare class AtpMcpServer {
      */
     private zodToJsonSchema;
     /**
-     * Start the MCP server
+     * Start the MCP server.
+     *
+     * By default the server speaks MCP over stdio. Pass
+     * `{ transport: 'http' }` to serve the Streamable HTTP transport instead:
+     * a node:http server routes POST/GET/DELETE on /mcp through per-session
+     * StreamableHTTPServerTransport instances, each backed by a fresh MCP
+     * Server built via the same construction path as the stdio server.
+     */
+    start(options?: IServerStartOptions): Promise<void>;
+    /**
+     * Start the Streamable HTTP transport: a node:http server (no express
+     * dependency) that routes /mcp through per-session transports.
+     *
+     * Binding defaults to the configured host, with 'localhost' pinned to the
+     * IPv4 loopback 127.0.0.1 so the bind address (and the DNS-rebinding
+     * allowlist) is deterministic across platforms whose resolvers disagree
+     * about ::1 vs 127.0.0.1. Exposing the server beyond loopback (e.g.
+     * --host 0.0.0.0) is the operator's responsibility to secure.
+     */
+    private startHttpTransport;
+    /**
+     * Route a single HTTP request. Only /mcp is served; the SDK transport does
+     * the MCP-level work (method dispatch, session validation, SSE streaming).
+     */
+    private handleHttpRequest;
+    /**
+     * Create a Streamable HTTP session: a stateful transport (server-minted
+     * session id) wired to a fresh MCP Server from the shared factory. The
+     * session registers itself in httpSessions once the SDK accepts the
+     * initialize request, and removes itself when the transport closes (DELETE,
+     * client disconnect, or shutdown).
+     */
+    private createHttpSession;
+    /**
+     * Read and parse a JSON request body, bounding its size. Responds (413/400)
+     * and resolves to undefined when the body is unusable; the caller must stop
+     * processing the request in that case.
+     */
+    private readJsonBody;
+    /**
+     * Write a JSON-RPC-shaped HTTP error response (the same shape the SDK
+     * transport uses for its own protocol-level rejections).
+     */
+    private writeJsonRpcError;
+    /**
+     * The address the http transport is bound to, or null when the http
+     * transport is not running. Exposed so callers (and tests binding port 0)
+     * can discover the actual ephemeral port.
      */
-    start(): Promise<void>;
+    getHttpAddress(): {
+        host: string;
+        port: number;
+    } | null;
     /**
      * Stop the MCP server
      */
@@ -131,4 +222,3 @@ export declare class AtpMcpServer {
  *   await server.start();
  */
 export default AtpMcpServer;
-//# sourceMappingURL=index.d.ts.map