π The fast, Pythonic way to build MCP servers and clients.
Add advanced ATProto features: replies, rich text, quotes, and images
zzstoatzz3264c8560653
diff --git a/examples/atproto_mcp/README.md b/examples/atproto_mcp/README.mdindex ecc680181..1b7a7f259 100644--- a/examples/atproto_mcp/README.md+++ b/examples/atproto_mcp/README.md@@ -15,11 +15,18 @@ The server provides two types of capabilities:### Tools (Actions that modify state)+Basic interactions:- **post_to_bluesky**: Create new posts on Bluesky- **follow_user**: Follow a user by handle- **like_post**: Like a post by URI- **repost**: Repost content by URI+Advanced interactions:+- **reply_to_post**: Reply to posts and create threaded conversations+- **post_with_rich_text**: Create posts with clickable links and @mentions+- **quote_post**: Quote and comment on other posts+- **post_with_images**: Create posts with up to 4 images+## Setup1. Create a `.env` file in the root directory with your Bluesky credentials:@@ -40,7 +47,9 @@ pip install -e .python -m atproto_mcp```-## Usage Example+## Usage Examples++### Basic Usage```pythonfrom fastmcp import Client@@ -50,18 +59,53 @@ async def demo():async with Client(atproto_mcp) as client:# Read resourcesstatus = await client.read_resource("atproto://profile/status")- print(f"Connected as: {status}")-- timeline = await client.read_resource("atproto://timeline?limit=5")- print(f"Timeline: {timeline}")+ timeline = await client.read_resource("atproto://timeline")- # Use tools for actions+ # Basic postpost = await client.call_tool("post_to_bluesky", {"text": "Hello from FastMCP!"})- print(f"Posted: {post}")```+### Advanced Usage++```python+# Reply to a post+reply = await client.call_tool("reply_to_post", {+ "parent_uri": "at://did:plc:xxx/app.bsky.feed.post/yyy",+ "text": "Great point! Here's my perspective..."+})++# Post with rich text (links and mentions)+rich_post = await client.call_tool("post_with_rich_text", {+ "text": "Check out this article by @jlowin.dev",+ "links": [{"text": "this article", "url": "https://example.com"}],+ "mentions": [{"handle": "jlowin.dev", "display_text": "@jlowin.dev"}]+})++# Quote a post+quote = await client.call_tool("quote_post", {+ "text": "This is an important perspective on AI safety:",+ "quoted_uri": "at://did:plc:xxx/app.bsky.feed.post/yyy"+})++# Post with images+image_post = await client.call_tool("post_with_images", {+ "text": "Beautiful sunset today! π ",+ "image_urls": ["https://example.com/sunset.jpg"],+ "alt_texts": ["A sunset over the ocean"]+})+```++## AI Assistant Use Cases++This MCP server is designed to enable powerful AI assistant interactions:++- **"Reply to that post about climate change with these research findings"** - Uses reply_to_post with rich text links+- **"Share this article with my thoughts"** - Uses quote_post or post_with_rich_text+- **"Post this chart with an explanation"** - Uses post_with_images+- **"Start a discussion about AI safety and mention @expert.bsky"** - Uses post_with_rich_text with mentions+## ArchitectureThe server is organized with:diff --git a/examples/atproto_mcp/pyproject.toml b/examples/atproto_mcp/pyproject.tomlindex 95abd5aa4..e874b5191 100644--- a/examples/atproto_mcp/pyproject.toml+++ b/examples/atproto_mcp/pyproject.toml@@ -4,12 +4,13 @@ version = "0.1.0"description = "Add your description here"readme = "README.md"authors = [{ name = "zzstoatzz", email = "[email protected]" }]-requires-python = ">=3.10"+requires-python = ">=3.12"dependencies = ["fastmcp>=0.8.0","atproto@git+https://github.com/MarshalX/atproto.git@refs/pull/605/head","pydantic-settings>=2.0.0","websockets>=15.0.1",+ "httpx>=0.27.0",][project.scripts]diff --git a/examples/atproto_mcp/src/atproto_mcp/_atproto.py b/examples/atproto_mcp/src/atproto_mcp/_atproto.pyindex c13663a6b..31937a3ed 100644--- a/examples/atproto_mcp/src/atproto_mcp/_atproto.py+++ b/examples/atproto_mcp/src/atproto_mcp/_atproto.py@@ -2,18 +2,23 @@from datetime import datetime-from atproto import Client+from atproto import Client, modelsfrom atproto_mcp.settings import settingsfrom atproto_mcp.types import (FollowResult,+ ImagePostResult,LikeResult,Notification,NotificationsResult,Post,PostResult,ProfileInfo,+ QuotePostResult,+ ReplyResult,RepostResult,+ RichTextLink,+ RichTextMention,SearchResult,TimelineResult,)@@ -300,3 +305,226 @@ def repost_by_uri(uri: str) -> RepostResult:repost_uri=None,error=str(e),)+++def reply_to_post(+ parent_uri: str, text: str, root_uri: str | None = None+) -> ReplyResult:+ """Reply to a post."""+ try:+ client = get_client()++ # Get parent post to extract CID+ parent_post = client.app.bsky.feed.get_posts(params={"uris": [parent_uri]})+ if not parent_post.posts:+ raise ValueError("Parent post not found")++ parent_cid = parent_post.posts[0].cid+ parent_ref = models.create_strong_ref({"uri": parent_uri, "cid": parent_cid})++ # If no root_uri provided, parent is the root+ if root_uri is None:+ root_ref = parent_ref+ else:+ # Get root post CID+ root_post = client.app.bsky.feed.get_posts(params={"uris": [root_uri]})+ if not root_post.posts:+ raise ValueError("Root post not found")+ root_cid = root_post.posts[0].cid+ root_ref = models.create_strong_ref({"uri": root_uri, "cid": root_cid})++ # Create the reply+ reply = client.send_post(+ text=text,+ reply_to=models.AppBskyFeedPost.ReplyRef(parent=parent_ref, root=root_ref),+ )++ return ReplyResult(+ success=True,+ uri=reply.uri,+ cid=reply.cid,+ parent_uri=parent_uri,+ root_uri=root_uri or parent_uri,+ error=None,+ )+ except Exception as e:+ return ReplyResult(+ success=False,+ uri=None,+ cid=None,+ parent_uri=None,+ root_uri=None,+ error=str(e),+ )+++def create_post_with_rich_text(+ text: str,+ links: list[RichTextLink] | None = None,+ mentions: list[RichTextMention] | None = None,+) -> PostResult:+ """Create a post with rich text formatting (links and mentions)."""+ try:+ client = get_client()+ facets = []++ # Process links+ if links:+ for link in links:+ # Find the position of link text in the main text+ start = text.find(link["text"])+ if start == -1:+ continue+ end = start + len(link["text"])++ facets.append(+ models.AppBskyRichtextFacet.Main(+ features=[models.AppBskyRichtextFacet.Link(uri=link["url"])],+ index=models.AppBskyRichtextFacet.ByteSlice(+ byte_start=len(text[:start].encode("UTF-8")),+ byte_end=len(text[:end].encode("UTF-8")),+ ),+ )+ )++ # Process mentions+ if mentions:+ for mention in mentions:+ display_text = mention.get("display_text") or f"@{mention['handle']}"+ # Find the position of mention in the main text+ start = text.find(display_text)+ if start == -1:+ continue+ end = start + len(display_text)++ # Resolve handle to DID+ resolved = client.app.bsky.actor.search_actors(+ params={"q": mention["handle"], "limit": 1}+ )+ if not resolved.actors:+ continue++ did = resolved.actors[0].did+ facets.append(+ models.AppBskyRichtextFacet.Main(+ features=[models.AppBskyRichtextFacet.Mention(did=did)],+ index=models.AppBskyRichtextFacet.ByteSlice(+ byte_start=len(text[:start].encode("UTF-8")),+ byte_end=len(text[:end].encode("UTF-8")),+ ),+ )+ )++ # Send the post with facets+ post = client.send_post(text=text, facets=facets if facets else None)++ return PostResult(+ success=True,+ uri=post.uri,+ cid=post.cid,+ text=text,+ created_at=datetime.now().isoformat(),+ error=None,+ )+ except Exception as e:+ return PostResult(+ success=False,+ uri=None,+ cid=None,+ text=None,+ created_at=None,+ error=str(e),+ )+++def create_quote_post(text: str, quoted_uri: str) -> QuotePostResult:+ """Create a quote post."""+ try:+ client = get_client()++ # Get the post to quote+ quoted_post = client.app.bsky.feed.get_posts(params={"uris": [quoted_uri]})+ if not quoted_post.posts:+ raise ValueError("Quoted post not found")++ # Create strong ref for the quoted post+ quoted_cid = quoted_post.posts[0].cid+ quoted_ref = models.create_strong_ref({"uri": quoted_uri, "cid": quoted_cid})++ # Create the embed+ embed = models.AppBskyEmbedRecord.Main(record=quoted_ref)++ # Send the quote post+ post = client.send_post(text=text, embed=embed)++ return QuotePostResult(+ success=True,+ uri=post.uri,+ cid=post.cid,+ quoted_uri=quoted_uri,+ error=None,+ )+ except Exception as e:+ return QuotePostResult(+ success=False,+ uri=None,+ cid=None,+ quoted_uri=None,+ error=str(e),+ )+++def create_post_with_images(+ text: str,+ image_urls: list[str],+ alt_texts: list[str] | None = None,+) -> ImagePostResult:+ """Create a post with images from URLs."""+ try:+ client = get_client()+ import httpx++ # Ensure alt_texts has same length as images+ if alt_texts is None:+ alt_texts = [""] * len(image_urls)+ elif len(alt_texts) < len(image_urls):+ alt_texts.extend([""] * (len(image_urls) - len(alt_texts)))++ images = []+ for i, url in enumerate(image_urls[:4]): # Max 4 images+ # Download image+ response = httpx.get(url)+ response.raise_for_status()++ # Upload to blob storage+ uploaded = client.upload_blob(response.content)++ images.append(+ {+ "image": uploaded.blob,+ "alt": alt_texts[i] if i < len(alt_texts) else "",+ }+ )++ # Send post with images+ post = client.send_images(+ text=text,+ images=[img["image"] for img in images],+ image_alts=[img["alt"] for img in images],+ )++ return ImagePostResult(+ success=True,+ uri=post.uri,+ cid=post.cid,+ image_count=len(images),+ error=None,+ )+ except Exception as e:+ return ImagePostResult(+ success=False,+ uri=None,+ cid=None,+ image_count=0,+ error=str(e),+ )diff --git a/examples/atproto_mcp/src/atproto_mcp/server.py b/examples/atproto_mcp/src/atproto_mcp/server.pyindex 73687f27f..8341fe328 100644--- a/examples/atproto_mcp/src/atproto_mcp/server.py+++ b/examples/atproto_mcp/src/atproto_mcp/server.py@@ -7,11 +7,16 @@ from pydantic import Fieldfrom atproto_mcp import _atprotofrom atproto_mcp.types import (FollowResult,+ ImagePostResult,LikeResult,NotificationsResult,PostResult,ProfileInfo,+ QuotePostResult,+ ReplyResult,RepostResult,+ RichTextLink,+ RichTextMention,SearchResult,TimelineResult,)@@ -93,3 +98,61 @@ def repost() -> RepostResult:"""Repost a post by its AT URI."""return _atproto.repost_by_uri(uri)+++# Advanced tools for richer interactions+@atproto_mcp.tool+def reply_to_post(+ parent_uri: Annotated[str, Field(description="The AT URI of the post to reply to")],+ text: Annotated[str, Field(max_length=300, description="The reply text")],+ root_uri: Annotated[+ str | None, Field(description="The AT URI of the thread root (optional)")+ ] = None,+) -> ReplyResult:+ """Reply to a post, creating a threaded conversation."""+ return _atproto.reply_to_post(parent_uri, text, root_uri)+++@atproto_mcp.tool+def post_with_rich_text(+ text: Annotated[+ str,+ Field(+ max_length=300,+ description="The post text with placeholders for links/mentions",+ ),+ ],+ links: Annotated[+ list[RichTextLink] | None, Field(description="Links to embed in the text")+ ] = None,+ mentions: Annotated[+ list[RichTextMention] | None, Field(description="User mentions to embed")+ ] = None,+) -> PostResult:+ """Create a post with rich text formatting including clickable links and mentions."""+ return _atproto.create_post_with_rich_text(text, links, mentions)+++@atproto_mcp.tool+def quote_post(+ text: Annotated[+ str, Field(max_length=300, description="Your commentary on the quoted post")+ ],+ quoted_uri: Annotated[str, Field(description="The AT URI of the post to quote")],+) -> QuotePostResult:+ """Create a quote post to share and comment on another post."""+ return _atproto.create_quote_post(text, quoted_uri)+++@atproto_mcp.tool+def post_with_images(+ text: Annotated[str, Field(max_length=300, description="The post text")],+ image_urls: Annotated[+ list[str], Field(max_length=4, description="URLs of images to attach (max 4)")+ ],+ alt_texts: Annotated[+ list[str] | None, Field(description="Alt text for each image")+ ] = None,+) -> ImagePostResult:+ """Create a post with images attached."""+ return _atproto.create_post_with_images(text, image_urls, alt_texts)diff --git a/examples/atproto_mcp/src/atproto_mcp/types.py b/examples/atproto_mcp/src/atproto_mcp/types.pyindex 4cf726448..d452dcb84 100644--- a/examples/atproto_mcp/src/atproto_mcp/types.py+++ b/examples/atproto_mcp/src/atproto_mcp/types.py@@ -103,3 +103,48 @@ class RepostResult(TypedDict):reposted_uri: str | Nonerepost_uri: str | Noneerror: str | None+++class ReplyResult(TypedDict):+ """Result of replying to a post."""++ success: bool+ uri: str | None+ cid: str | None+ parent_uri: str | None+ root_uri: str | None+ error: str | None+++class RichTextLink(TypedDict):+ """A link in rich text."""++ text: str+ url: str+++class RichTextMention(TypedDict):+ """A mention in rich text."""++ handle: str+ display_text: str | None+++class QuotePostResult(TypedDict):+ """Result of creating a quote post."""++ success: bool+ uri: str | None+ cid: str | None+ quoted_uri: str | None+ error: str | None+++class ImagePostResult(TypedDict):+ """Result of posting with images."""++ success: bool+ uri: str | None+ cid: str | None+ image_count: int+ error: str | None