@meowtrix/atproto-mcp 0.1.1

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 meowtrix
+
+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

@@ -0,0 +1,147 @@
+# atproto-mcp
+
+AT Protocol MCP server — gives AI agents the ability to navigate the AT Protocol.
+
+## Quick start (npx)
+
+Add this in your mcp config:
+
+```json
+{
+  "mcpServers": {
+    "atproto": {
+      "command": "npx",
+      "args": ["-y", "@meowtrix/atproto-mcp", "--stdio"],
+      "env": {
+        "ATPROTO_HANDLE": "your-handle.bsky.social",
+        "ATPROTO_APP_PASSWORD": "xxxx-xxxx-xxxx-xxxx"
+      }
+    }
+  }
+}
+```
+
+Generate an app password at [bsky.app/settings/app-passwords](https://bsky.app/settings/app-passwords).
+
+## Environment variables
+
+| Variable | Required | Default | Description |
+|---|---|---|---|
+| `ATPROTO_HANDLE` | Yes | — | Your AT Protocol handle (e.g. `alice.bsky.social`) |
+| `ATPROTO_APP_PASSWORD` | Yes | — | App password (not your main password) |
+| `ENABLE_INTERACTION_GUARDS` | No | `false` | Restrict replies/likes/reposts/follows to mutual connections |
+
+## HTTP mode
+
+Start the server on port 3001:
+
+```bash
+npm start
+```
+
+Then configure your MCP client to connect via HTTP:
+
+```json
+{
+  "mcpServers": {
+    "atproto": {
+      "url": "http://localhost:3001/mcp"
+    }
+  }
+}
+```
+
+## Docker
+
+### Docker Compose
+
+Create a `.env` file with your credentials:
+
+```
+ATPROTO_HANDLE=your-handle.bsky.social
+ATPROTO_APP_PASSWORD=xxxx-xxxx-xxxx-xxxx
+```
+
+Then run:
+
+```bash
+docker compose up
+```
+
+### Manual Docker
+
+```bash
+docker build -t atproto-mcp .
+
+docker run -p 3001:3001 \
+  -e ATPROTO_HANDLE=your-handle.bsky.social \
+  -e ATPROTO_APP_PASSWORD=xxxx-xxxx-xxxx-xxxx \
+  atproto-mcp
+```
+
+## Resources
+
+| Resource | URI | Description |
+|---|---|---|
+| My Repo Collections | `atproto:///collections` | Shows what record types (collection NSIDs) exist in your AT Protocol repo — useful for discovering what services and data you have |
+
+## Tools
+
+### Social
+
+| Tool | Description |
+|---|---|
+| `post` | Create a post (supports replies and @-mentions) |
+| `timeline` | Get your home timeline |
+| `discover_feed` | Browse the Discover / What's Hot feed |
+| `search_posts` | Search posts by keyword |
+| `search_users` | Search for user accounts |
+| `get_profile` | Get a user's profile |
+| `get_author_feed` | Get a user's posts |
+| `my_posts` | Get your own recent posts |
+| `get_post_thread` | Get a post thread with replies |
+| `like` | Like a post |
+| `unlike` | Remove a like |
+| `repost` | Repost a post |
+| `unrepost` | Remove a repost |
+| `follow` | Follow a user |
+| `unfollow` | Unfollow a user |
+| `delete_post` | Delete one of your posts |
+| `all_notifications` | List all notifications |
+| `unread_notifications` | List unread notifications |
+| `mark_notifications_read` | Mark notifications as read |
+
+### Protocol
+
+| Tool | Description |
+|---|---|
+| `whoami` | Check current authenticated session |
+| `resolve_did` | Resolve a handle to a DID and fetch DID document |
+| `get_record` | Fetch any record by repo/collection/rkey |
+| `list_records` | List records in a collection |
+| `describe_repo` | Get repo metadata and collections (defaults to your own repo) |
+| `get_blob` | Download a blob by DID and CID |
+| `upload_blob` | Upload a blob (image, etc.) |
+| `create_record` | Create a record in any collection |
+| `put_record` | Create or update a record by collection and rkey |
+| `delete_record` | Delete a record by collection and rkey |
+
+### Graph
+
+| Tool | Description |
+|---|---|
+| `update_profile` | Update your profile (display name, bio, avatar, banner) |
+| `get_lists` | Get a user's lists |
+| `get_list` | Get list details and items |
+| `get_suggested_follows` | Get follow suggestions |
+| `get_suggested_feeds` | Discover suggested custom feeds |
+| `get_feed` | Get posts from a custom feed |
+| `get_feed_generators` | Look up feed generator metadata |
+| `get_followers` | List a user's followers |
+| `get_follows` | List who a user follows |
+| `get_preferences` | Read your account preferences |
+| `put_preferences` | Replace all account preferences |
+
+## Interaction guards
+
+When `ENABLE_INTERACTION_GUARDS=true`, the server restricts engagement actions (replies, likes, reposts, follows) to users who follow you back. This prevents the AI from interacting with strangers unsupervised.

package/bin/cli.js

@@ -0,0 +1,5 @@
+#!/usr/bin/env node
+import { register } from "tsx/esm/api";
+
+register();
+await import("../src/server.ts");

package/package.json

@@ -0,0 +1,46 @@
+{
+  "name": "@meowtrix/atproto-mcp",
+  "version": "0.1.1",
+  "description": "AT Protocol MCP server — gives AI agents the ability to navigate the AT Protocol",
+  "type": "module",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/meowtrix/atproto-mcp"
+  },
+  "keywords": [
+    "atproto",
+    "bluesky",
+    "mcp",
+    "model-context-protocol"
+  ],
+  "engines": {
+    "node": ">=22"
+  },
+  "files": [
+    "bin/",
+    "src/",
+    "!src/**/*.test.ts"
+  ],
+  "bin": {
+    "atproto-mcp": "./bin/cli.js"
+  },
+  "scripts": {
+    "start": "node --import=tsx src/server.ts",
+    "test": "vitest run"
+  },
+  "dependencies": {
+    "@atcute/atproto": "^3.1.10",
+    "@atcute/bluesky": "^3.2.20",
+    "@atcute/client": "^4.2.1",
+    "@atcute/identity-resolver": "^1.2.2",
+    "@modelcontextprotocol/sdk": "^1.27.1",
+    "tsx": "^4.21.0",
+    "zod": "^3.24.0"
+  },
+  "devDependencies": {
+    "@types/node": "^24.12.0",
+    "typescript": "^5.9.3",
+    "vitest": "^4.0.18"
+  }
+}

package/src/bsky/constraints.ts

@@ -0,0 +1,97 @@
+import type { Client } from "@atcute/client";
+import type {} from "@atcute/bluesky";
+import type { Did, Handle } from "@atcute/lexicons";
+
+const asActor = (s: string) => s as Did & Handle;
+
+/**
+ * Server-side enforcement of reply and engagement constraints.
+ *
+ * Reply constraint: Cannot reply unless the authenticated user was
+ * @-mentioned in the thread or authored an ancestor (own thread).
+ *
+ * Engagement constraint (like/repost/follow): Allowed when the target
+ * is self or the target follows the authenticated user.
+ */
+
+export type ConstraintRpc = Pick<Client, "get">;
+
+export function* walkParentChain(thread: any): Generator<any> {
+  let current = thread;
+  while (current?.$type === "app.bsky.feed.defs#threadViewPost") {
+    yield current.post;
+    current = current.parent;
+  }
+}
+
+export async function validatePostConstraints(opts: {
+  postText: string;
+  facets: {
+    index: { byteStart: number; byteEnd: number };
+    features: [{ $type: string; did: string }];
+  }[];
+  threadData: any | null;
+  selfDid: string;
+}): Promise<string | null> {
+  const { threadData, selfDid } = opts;
+
+  // Top-level posts are always allowed (no reply constraint to check)
+  if (!threadData) return null;
+
+  // Check own-thread exemption
+  for (const post of walkParentChain(threadData)) {
+    if (post.author?.did === selfDid) {
+      return null;
+    }
+  }
+
+  // Check if user was @-mentioned anywhere in the thread
+  for (const post of walkParentChain(threadData)) {
+    const postFacets = post.record?.facets ?? [];
+    const mentionsSelf = postFacets.some((f: any) =>
+      f.features?.some(
+        (feat: any) =>
+          feat.$type === "app.bsky.richtext.facet#mention" &&
+          feat.did === selfDid,
+      ),
+    );
+    if (mentionsSelf) return null;
+  }
+
+  return "Reply constraint: cannot reply — you were not mentioned in the thread and it is not your own thread.";
+}
+
+/**
+ * Check if a user follows the authenticated user (opt-in engagement).
+ * Used for like/repost/follow constraints.
+ */
+export async function checkFollowsAgent(
+  did: string,
+  rpc: ConstraintRpc,
+): Promise<boolean> {
+  try {
+    const res = await rpc.get("app.bsky.actor.getProfiles", {
+      params: { actors: [asActor(did)] },
+    });
+    if (!res.ok) return false;
+    return !!res.data.profiles[0]?.viewer?.followedBy;
+  } catch {
+    return false;
+  }
+}
+
+/**
+ * Check if engagement (like/repost/follow) is allowed with a given DID.
+ *
+ * Allowed when any of:
+ * 1. The target is self (self-interaction)
+ * 2. The target follows the authenticated user (opt-in)
+ */
+export async function checkEngagementAllowed(
+  did: string,
+  selfDid: string,
+  rpc: ConstraintRpc,
+): Promise<boolean> {
+  if (did === selfDid) return true;
+  return checkFollowsAgent(did, rpc);
+}

package/src/bsky/facets.ts

@@ -0,0 +1,44 @@
+import { Client } from "@atcute/client";
+import { asHandle } from "../context.ts";
+
+export const MENTION_RE = /(^|\s)(@([a-zA-Z0-9]([a-zA-Z0-9-]{0,61}[a-zA-Z0-9])?(\.[a-zA-Z0-9]([a-zA-Z0-9-]{0,61}[a-zA-Z0-9])?)+))/g;
+
+export async function detectMentionFacets(
+  text: string,
+  rpc: Client,
+): Promise<
+  {
+    index: { byteStart: number; byteEnd: number };
+    features: [{ $type: "app.bsky.richtext.facet#mention"; did: string }];
+  }[]
+> {
+  const encoder = new TextEncoder();
+  const facets: Awaited<ReturnType<typeof detectMentionFacets>> = [];
+
+  for (const match of text.matchAll(MENTION_RE)) {
+    const handle = match[3]; // the handle without @
+    const mentionStart = match.index! + match[1].length; // skip leading whitespace
+    const mentionText = match[2]; // @handle
+
+    const byteStart = encoder.encode(text.slice(0, mentionStart)).byteLength;
+    const byteEnd = byteStart + encoder.encode(mentionText).byteLength;
+
+    try {
+      const res = await rpc.get("com.atproto.identity.resolveHandle", {
+        params: { handle: asHandle(handle) },
+      });
+      if (!res.ok) {
+        console.warn(`Failed to resolve handle @${handle}: ${(res as any).data?.message}`);
+        continue;
+      }
+      facets.push({
+        index: { byteStart, byteEnd },
+        features: [{ $type: "app.bsky.richtext.facet#mention", did: res.data.did }],
+      });
+    } catch (e) {
+      console.warn(`Failed to resolve handle @${handle}:`, e);
+    }
+  }
+
+  return facets;
+}

package/src/bsky/graph-tools.ts

@@ -0,0 +1,325 @@
+import type { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+import type {} from "@atcute/atproto";
+import type { AppBskyGraphDefs } from "@atcute/bluesky";
+import type { Did, Handle, Nsid } from "@atcute/lexicons";
+import { z } from "zod";
+import {
+  getCtx,
+  text,
+  error,
+  asActor,
+  asUri,
+  asUris,
+  parseAtUri,
+  validateBlobRef,
+} from "../context.ts";
+import { slimActor, slimFeedItem } from "./slim.ts";
+
+export function registerGraphTools(server: McpServer) {
+  server.registerTool(
+    "update_profile",
+    {
+      description:
+        "Update your Bluesky profile (read-modify-write). Only provided fields are changed",
+      inputSchema: {
+        displayName: z.string().optional().describe("Display name"),
+        description: z.string().optional().describe("Profile bio/description"),
+        avatar: z
+          .string()
+          .optional()
+          .describe(
+            "Avatar blob ref as JSON string — use the exact complete object returned by upload_blob (includes $type, ref, mimeType, size). Omit to keep existing.",
+          ),
+        banner: z
+          .string()
+          .optional()
+          .describe(
+            "Banner blob ref as JSON string — use the exact complete object returned by upload_blob (includes $type, ref, mimeType, size). Omit to keep existing.",
+          ),
+      },
+    },
+    async ({ displayName, description, avatar, banner }) => {
+      try {
+        // Read existing profile record
+        let existing: Record<string, unknown> = {};
+        try {
+          const getRes = await getCtx().rpc.get("com.atproto.repo.getRecord", {
+            params: {
+              repo: getCtx().session.session!.did as Did & Handle,
+              collection: "app.bsky.actor.profile" as Nsid,
+              rkey: "self",
+            },
+          });
+          if (getRes.ok) {
+            existing = getRes.data.value as Record<string, unknown>;
+          }
+        } catch {
+          // No existing profile — start fresh
+        }
+
+        // Merge only provided fields
+        const updated: Record<string, unknown> = {
+          $type: "app.bsky.actor.profile",
+          ...existing,
+        };
+        if (displayName !== undefined) updated.displayName = displayName;
+        if (description !== undefined) updated.description = description;
+
+        if (avatar) {
+          let parsed: unknown;
+          try {
+            parsed = JSON.parse(avatar);
+          } catch {
+            return error(
+              "avatar is not valid JSON. Pass the exact JSON object returned by upload_blob.",
+            );
+          }
+          const err = validateBlobRef("avatar", parsed);
+          if (err) return error(err);
+          updated.avatar = parsed;
+        }
+
+        if (banner) {
+          let parsed: unknown;
+          try {
+            parsed = JSON.parse(banner);
+          } catch {
+            return error(
+              "banner is not valid JSON. Pass the exact JSON object returned by upload_blob.",
+            );
+          }
+          const err = validateBlobRef("banner", parsed);
+          if (err) return error(err);
+          updated.banner = parsed;
+        }
+
+        const res = await getCtx().rpc.post("com.atproto.repo.putRecord", {
+          input: {
+            repo: getCtx().session.session!.did,
+            collection: "app.bsky.actor.profile",
+            rkey: "self",
+            record: updated,
+          },
+        });
+        if (!res.ok) {
+          console.error(
+            "[atproto] putRecord failed:",
+            JSON.stringify(res.data),
+          );
+          return error(res.data);
+        }
+        return text(res.data);
+      } catch (e) {
+        return error(e);
+      }
+    },
+  );
+
+  server.registerTool(
+    "get_lists",
+    {
+      description: "Get a user's lists",
+      inputSchema: {
+        actor: z.string().describe("Handle or DID of the user"),
+        limit: z
+          .number()
+          .optional()
+          .describe("Max results (default 50, max 100)"),
+        cursor: z.string().optional().describe("Pagination cursor"),
+      },
+    },
+    async ({ actor, limit, cursor }) => {
+      try {
+        const res = await getCtx().rpc.get("app.bsky.graph.getLists", {
+          params: { actor: asActor(actor), limit: limit ?? 50, cursor },
+        });
+        if (!res.ok) return error(res.data.message);
+        return text(res.data);
+      } catch (e) {
+        return error(e);
+      }
+    },
+  );
+
+  server.registerTool(
+    "get_list",
+    {
+      description: "Get list details and items",
+      inputSchema: {
+        list: z.string().describe("AT-URI of the list (must start with at://)"),
+        limit: z
+          .number()
+          .optional()
+          .describe("Max items (default 50, max 100)"),
+        cursor: z.string().optional().describe("Pagination cursor"),
+      },
+    },
+    async ({ list, limit, cursor }) => {
+      try {
+        const res = await getCtx().rpc.get("app.bsky.graph.getList", {
+          params: { list: asUri(list), limit: limit ?? 50, cursor },
+        });
+        if (!res.ok) return error(res.data.message);
+        return text({
+          cursor: res.data.cursor,
+          list: res.data.list,
+          items: res.data.items.map((i: AppBskyGraphDefs.ListItemView) => ({
+            uri: i.uri,
+            subject: slimActor(i.subject),
+          })),
+        });
+      } catch (e) {
+        return error(e);
+      }
+    },
+  );
+
+  server.registerTool(
+    "get_suggested_follows",
+    {
+      description: "Get follow suggestions based on a user",
+      inputSchema: {
+        actor: z.string().describe("Handle or DID to base suggestions on"),
+      },
+    },
+    async ({ actor }) => {
+      try {
+        const res = await getCtx().rpc.get(
+          "app.bsky.graph.getSuggestedFollowsByActor",
+          {
+            params: { actor: asActor(actor) },
+          },
+        );
+        if (!res.ok) return error(res.data.message);
+        return text({ suggestions: res.data.suggestions.map(slimActor) });
+      } catch (e) {
+        return error(e);
+      }
+    },
+  );
+
+  server.registerTool(
+    "get_suggested_feeds",
+    {
+      description: "Discover suggested custom feeds",
+      inputSchema: {
+        limit: z
+          .number()
+          .optional()
+          .describe("Max results (default 50, max 100)"),
+        cursor: z.string().optional().describe("Pagination cursor"),
+      },
+    },
+    async ({ limit, cursor }) => {
+      try {
+        const res = await getCtx().rpc.get("app.bsky.feed.getSuggestedFeeds", {
+          params: { limit: limit ?? 50, cursor },
+        });
+        if (!res.ok) return error(res.data.message);
+        return text(res.data);
+      } catch (e) {
+        return error(e);
+      }
+    },
+  );
+
+  server.registerTool(
+    "get_feed",
+    {
+      description: "Get posts from a custom feed",
+      inputSchema: {
+        feed: z
+          .string()
+          .describe("AT-URI of the feed generator (must start with at://)"),
+        limit: z
+          .number()
+          .optional()
+          .describe("Max posts (default 50, max 100)"),
+        cursor: z.string().optional().describe("Pagination cursor"),
+      },
+    },
+    async ({ feed, limit, cursor }) => {
+      try {
+        const res = await getCtx().rpc.get("app.bsky.feed.getFeed", {
+          params: { feed: asUri(feed), limit: limit ?? 50, cursor },
+        });
+        if (!res.ok) return error(res.data.message);
+        return text({
+          cursor: res.data.cursor,
+          feed: res.data.feed.map(slimFeedItem),
+        });
+      } catch (e) {
+        return error(e);
+      }
+    },
+  );
+
+  server.registerTool(
+    "get_feed_generators",
+    {
+      description: "Look up metadata for one or more feed generators",
+      inputSchema: {
+        feeds: z
+          .array(z.string())
+          .describe(
+            "Array of AT-URIs of feed generators (each must start with at://)",
+          ),
+      },
+    },
+    async ({ feeds }) => {
+      try {
+        const res = await getCtx().rpc.get("app.bsky.feed.getFeedGenerators", {
+          params: { feeds: asUris(feeds) },
+        });
+        if (!res.ok) return error(res.data.message);
+        return text(res.data);
+      } catch (e) {
+        return error(e);
+      }
+    },
+  );
+
+  server.registerTool(
+    "get_preferences",
+    {
+      description: "Read your account preferences",
+    },
+    async () => {
+      try {
+        const res = await getCtx().rpc.get("app.bsky.actor.getPreferences", {
+          params: {},
+        });
+        if (!res.ok) return error(res.data.message);
+        return text(res.data);
+      } catch (e) {
+        return error(e);
+      }
+    },
+  );
+
+  server.registerTool(
+    "put_preferences",
+    {
+      description:
+        "Replace all account preferences. WARNING: this overwrites all existing preferences",
+      inputSchema: {
+        preferences: z
+          .string()
+          .describe("JSON string of the preferences array to set"),
+      },
+    },
+    async ({ preferences }) => {
+      try {
+        const parsed = JSON.parse(preferences);
+        const res = await getCtx().rpc.post("app.bsky.actor.putPreferences", {
+          input: { preferences: parsed },
+          as: null,
+        });
+        if (!res.ok) return error(res.data.message);
+        return text({ success: true });
+      } catch (e) {
+        return error(e);
+      }
+    },
+  );
+}