Merge pull request #84 from marthendalnunes/feat/mcp-resources

feat: add mcp resources

Author: christopherwxyz

Cargo.lock

@@ -84,6 +84,7 @@ coins-bip39 = "0.12.0"
 uuid = { version = "1.11.0", features = ["v4", "serde"] }
 chrono = { version = "0.4.39", features = ["serde"] }
 url = "2.3.1"
+percent-encoding = "2.3"
 rand = "0.9.1"
 
 # HTTP client
@@ -93,7 +94,7 @@ reqwest = { version = "0.12.10", features = ["stream"] }
 cadence = "1.5.0"
 
 # MCP
-rmcp = { version = "0.12.0", features = ["server", "client", "transport-streamable-http-server", "transport-child-process", "transport-io"] }
+rmcp = { version = "0.14.0", features = ["server", "client", "transport-streamable-http-server", "transport-child-process", "transport-io"] }
 
 [build-dependencies]
 tonic-prost-build = "0.14.1"

Cargo.toml

@@ -8,7 +8,7 @@ The Model Context Protocol (MCP) is a specification that allows AI assistants to
 
 ## Implementation
 
-Waypoint uses [rmcp](https://github.com/modelcontextprotocol/rust-sdk) version **0.10.0**, the official Rust SDK for the Model Context Protocol. The implementation leverages the latest macro-based API patterns and the new **Streamable HTTP** transport (MCP spec version 2025-03-26):
+Waypoint uses [rmcp](https://github.com/modelcontextprotocol/rust-sdk) version **0.14.0**, the official Rust SDK for the Model Context Protocol. The implementation leverages the latest macro-based API patterns and the new **Streamable HTTP** transport (MCP spec version 2025-03-26):
 
 - **`#[tool_router]`**: Generates tool routing logic for service implementations
 - **`#[prompt_router]`**: Generates prompt routing logic for service implementations
@@ -85,6 +85,61 @@ The Waypoint MCP integration provides the following tools to AI assistants:
 
 > **Note**: This implementation provides access to Farcaster user data, casts, reactions, links, and verifications via a comprehensive interface. It allows accessing users by FID or username and supports exploring the social graph through follow relationships.
 
+## Resources
+
+Waypoint also exposes MCP resources that mirror tool outputs. These are read-only, JSON resources that can be fetched via `resources/read` with a `waypoint://` URI.
+
+### URI Design (RFC 3986 / RFC 6570)
+
+Resource URIs follow [RFC 3986](https://www.rfc-editor.org/rfc/rfc3986) (URI syntax) and [RFC 6570](https://www.rfc-editor.org/rfc/rfc6570) (URI Template) standards:
+
+- **Path segments** identify resource type and simple identifiers (FID, hash)
+- **Query parameters** (`?url=...`) are used for complex values like URLs
+
+This design ensures proper URL encoding, avoids ambiguity, and follows web standards.
+
+### Resource Templates
+
+#### Users
+- `waypoint://users/{fid}`: User profile by FID
+- `waypoint://users/by-username/{username}`: User profile by username
+
+#### Verifications
+- `waypoint://verifications/{fid}`: Verified addresses for a FID
+
+#### Casts
+- `waypoint://casts/{fid}/{hash}`: Specific cast by author FID + hash
+- `waypoint://casts/by-fid/{fid}`: Recent casts by FID
+- `waypoint://casts/by-mention/{fid}`: Casts mentioning a FID
+- `waypoint://casts/by-parent/{fid}/{hash}`: Replies to a parent cast
+- `waypoint://casts/by-parent-url{?url}`: Replies to a parent URL (RFC 6570 query expansion)
+
+#### Conversations
+- `waypoint://conversations/{fid}/{hash}`: Full conversation thread for a cast (includes replies, participants, parent context, quoted casts)
+
+#### Reactions
+- `waypoint://reactions/by-fid/{fid}`: Reactions by FID
+- `waypoint://reactions/by-target-cast/{fid}/{hash}`: Reactions to a target cast
+- `waypoint://reactions/by-target-url{?url}`: Reactions to a target URL (RFC 6570 query expansion)
+
+#### Links
+- `waypoint://links/by-fid/{fid}`: Links by FID (defaults to `follow`)
+- `waypoint://links/by-target/{fid}`: Links to a target FID (defaults to `follow`)
+- `waypoint://links/compact-state/{fid}`: Link compact state by FID
+
+### URL Query Parameters
+
+For resources that accept URLs (e.g., `by-parent-url`, `by-target-url`), pass the URL as a query parameter:
+
+```
+waypoint://casts/by-parent-url?url=https%3A%2F%2Fexample.com%2Fpost%2F123
+waypoint://reactions/by-target-url?url=https%3A%2F%2Fwarpcast.com%2F~%2Fchannel%2Ftest
+```
+
+The URL value should be percent-encoded per RFC 3986.
+
+List-style resources use the same default limit as tools (10), unless the tool supports explicit limits.
+
 ### User Tools
 
 #### Get User by FID
@@ -778,23 +833,29 @@ AI assistants can connect to Waypoint's MCP service in several ways:
 
 ### HTTP Mode Connection
 
-Connect to the MCP service using the SSE endpoint:
+Connect to the MCP service using the Streamable HTTP endpoint:
+
+```
+http://waypoint-host:8000/mcp
+```
+
+For raw HTTP clients, initialize a session first and include an Accept header that supports both JSON and event streams:
 
 ```
-http://waypoint-host:8000/sse
+Accept: application/json, text/event-stream
 ```
 
 Example connection using the MCP client library:
 ```javascript
 import { createClient } from "@modelcontextprotocol/client";
 
 const client = createClient({
-  url: "http://waypoint-host:8000/sse"
+  url: "http://waypoint-host:8000/mcp"
 });
 
 // List available tools
 const toolList = await client.listTools();
-console.log(toolList); // Will show get_user_by_fid, get_verifications, get_casts_by_user tools
+console.log(toolList); // Will show get_user_by_fid, get_verifications_by_fid, get_casts_by_fid tools
 
 // Get user profile data
 const userData = await client.callTool({
@@ -805,7 +866,7 @@ console.log(userData);
 
 // Get recent casts from a user
 const casts = await client.callTool({
-  name: "get_casts_by_user",
+  name: "get_casts_by_fid",
   input: { fid: 12345, limit: 5 }
 });
 console.log(casts);
@@ -816,7 +877,7 @@ console.log(casts);
 
 When using Docker Compose, the MCP service is already configured and exposed:
 
-- MCP Service: `http://localhost:8000/sse`
+- MCP Service: `http://localhost:8000/mcp`
 
 The service is enabled by default and will automatically start with Waypoint.
 

docs/mcp.md

@@ -71,6 +71,7 @@ async fn serve_mcp(matches: &ArgMatches) -> Result<()> {
     // Configure the Streamable HTTP server
     let server_config = StreamableHttpServerConfig {
         sse_keep_alive: Some(std::time::Duration::from_secs(15)),
+        sse_retry: None,
         stateful_mode: true,
         cancellation_token: cancellation_token.clone(),
     };

src/commands/mcp/mod.rs

@@ -101,7 +101,7 @@ impl MooCow {
         }
     }
 
-    fn _create_resource_text(&self, uri: &str, name: &str) -> Resource {
+    fn create_resource_text(uri: &str, name: &str) -> Resource {
         RawResource::new(uri, name.to_string()).no_annotation()
     }
 
@@ -179,7 +179,7 @@ impl MooCow {
 impl ServerHandler for MooCow {
     fn get_info(&self) -> ServerInfo {
         ServerInfo {
-            protocol_version: ProtocolVersion::V_2024_11_05,
+            protocol_version: super::handlers::MCP_PROTOCOL_VERSION,
             capabilities: ServerCapabilities::builder()
                 .enable_prompts()
                 .enable_resources()
@@ -192,13 +192,13 @@ impl ServerHandler for MooCow {
 
     async fn list_resources(
         &self,
-        _request: Option<PaginatedRequestParam>,
+        _request: Option<PaginatedRequestParams>,
         _: RequestContext<RoleServer>,
     ) -> Result<ListResourcesResult, McpError> {
         Ok(ListResourcesResult {
             resources: vec![
-                self._create_resource_text("str:///cow/info", "cow-info"),
-                self._create_resource_text("memo://moo-facts", "moo-facts"),
+                Self::create_resource_text("str:///cow/info", "cow-info"),
+                Self::create_resource_text("memo://moo-facts", "moo-facts"),
             ],
             next_cursor: None,
             meta: None,
@@ -207,7 +207,7 @@ impl ServerHandler for MooCow {
 
     async fn read_resource(
         &self,
-        ReadResourceRequestParam { uri }: ReadResourceRequestParam,
+        ReadResourceRequestParams { uri, .. }: ReadResourceRequestParams,
         _: RequestContext<RoleServer>,
     ) -> Result<ReadResourceResult, McpError> {
         match uri.as_str() {
@@ -230,7 +230,7 @@ impl ServerHandler for MooCow {
 
     async fn list_resource_templates(
         &self,
-        _request: Option<PaginatedRequestParam>,
+        _request: Option<PaginatedRequestParams>,
         _: RequestContext<RoleServer>,
     ) -> Result<ListResourceTemplatesResult, McpError> {
         Ok(ListResourceTemplatesResult {
@@ -340,6 +340,7 @@ impl Service for McpService {
         // Configure the Streamable HTTP server
         let server_config = StreamableHttpServerConfig {
             sse_keep_alive: Some(std::time::Duration::from_secs(15)),
+            sse_retry: None,
             stateful_mode: true,
             cancellation_token: ct_for_shutdown.clone(),
         };

src/services/mcp/base.rs

@@ -100,9 +100,9 @@ where
         tracing::info!("MCP: Fetching cast with FID: {} and hash: {}", fid, hash_hex);
 
         // Convert hex hash to bytes
-        let hash_bytes = match hex::decode(hash_hex.trim_start_matches("0x")) {
+        let hash_bytes = match super::utils::parse_hash_bytes(hash_hex) {
             Ok(bytes) => bytes,
-            Err(_) => return format!("Invalid hash format: {}", hash_hex),
+            Err(message) => return message,
         };
 
         // Use the data context to fetch the cast
@@ -177,9 +177,9 @@ where
         );
 
         // Convert hex hash to bytes
-        let parent_hash_bytes = match hex::decode(parent_hash_hex.trim_start_matches("0x")) {
+        let parent_hash_bytes = match super::utils::parse_hash_bytes(parent_hash_hex) {
             Ok(bytes) => bytes,
-            Err(_) => return format!("Invalid hash format: {}", parent_hash_hex),
+            Err(message) => return message,
         };
 
         // Use the data context to fetch replies
@@ -328,9 +328,9 @@ where
         tracing::info!("MCP: Fetching conversation for cast hash: {}", cast_hash);
 
         // Convert hex hash to bytes
-        let hash_bytes = match hex::decode(cast_hash.trim_start_matches("0x")) {
+        let hash_bytes = match super::utils::parse_hash_bytes(cast_hash) {
             Ok(bytes) => bytes,
-            Err(e) => return format!("Invalid cast hash: {}", e),
+            Err(message) => return format!("Invalid cast hash: {}", message),
         };
 
         // Fetch the root cast
@@ -659,13 +659,13 @@ where
 
         // The hash is stored in the Message's id field
         // This is from the Message.hash property in the protobuf
-        let parent_hash = match hex::decode(_parent_cast.id.value().trim_start_matches("0x")) {
+        let parent_hash = match super::utils::parse_hash_bytes(_parent_cast.id.value()) {
             Ok(hash_bytes) => hash_bytes,
-            Err(e) => {
+            Err(message) => {
                 tracing::error!(
                     "Failed to decode cast hash from ID: {} - {}",
                     _parent_cast.id.value(),
-                    e
+                    message
                 );
                 // If we can't decode the hash, use the raw bytes as fallback
                 // This is a last resort and may not produce correct results