mcp-resources-guide

What this skill does

You are an expert in implementing MCP resources using the rmcp crate, with deep knowledge of resource patterns, URI design, and data fetching strategies.

## Your Expertise

You guide developers on:
- Resource design and URI patterns
- Resource listing and discovery
- Content fetching and caching
- MIME type handling
- Streaming large resources
- Resource subscriptions and updates
- Testing resource implementations

## What are MCP Resources?

**Resources** are data sources that MCP servers expose to AI assistants. They provide context through files, database records, API responses, or any retrievable data.

### Resource Characteristics

- **URI-addressable**: Each resource has a unique URI
- **Typed**: Resources have MIME types
- **Listable**: Servers can list available resources
- **Fetchable**: Clients can retrieve resource content
- **Cacheable**: Support for caching strategies

### Resource vs Tools

- **Tools**: Actions that modify state or perform computations
- **Resources**: Data that provides context (read-only typically)

## Resource URI Patterns

### URI Design Principles

Good URI design is crucial for resource organization:

```rust
// Pattern 1: Hierarchical paths
"file:///project/src/main.rs"
"db://users/123"
"api://weather/san-francisco/current"

// Pattern 2: Query-style
"data://records?type=user&id=123"
"search://results?q=rust+mcp&limit=10"

// Pattern 3: Template-based
"user://{user_id}"
"document://{collection}/{document_id}"
"metric://{service}/{metric_name}/{timerange}"
```

### URI Components

```
scheme://authority/path?query#fragment
  │        │        │    │      │
  │        │        │    │      └─ Optional fragment
  │        │        │    └─ Optional query parameters
  │        │        └─ Resource path
  │        └─ Optional authority (host, port)
  └─ Resource type identifier
```

## Implementing Resources

### Basic Resource Implementation

```rust
use rmcp::prelude::*;
use serde::{Deserialize, Serialize};

#[derive(Clone)]
struct FileSystemResource {
    root_path: PathBuf,
}

impl FileSystemResource {
    fn new(root_path: impl Into<PathBuf>) -> Self {
        Self {
            root_path: root_path.into(),
        }
    }

    // List resources
    async fn list_resources(&self) -> Result<Vec<ResourceInfo>, Error> {
        let mut resources = Vec::new();

        let entries = tokio::fs::read_dir(&self.root_path).await?;
        let mut entries = entries;

        while let Some(entry) = entries.next_entry().await? {
            let path = entry.path();
            let relative_path = path.strip_prefix(&self.root_path)?;

            let uri = format!("file:///{}", relative_path.display());

            resources.push(ResourceInfo {
                uri,
                name: entry.file_name().to_string_lossy().to_string(),
                description: Some(format!("File: {}", relative_path.display())),
                mime_type: Some(self.detect_mime_type(&path)),
            });
        }

        Ok(resources)
    }

    // Fetch resource content
    async fn fetch_resource(&self, uri: &str) -> Result<ResourceContent, Error> {
        // Parse URI to extract path
        let path = self.parse_uri(uri)?;
        let full_path = self.root_path.join(&path);

        // Read file content
        let content = tokio::fs::read_to_string(&full_path).await?;
        let mime_type = self.detect_mime_type(&full_path);

        Ok(ResourceContent {
            uri: uri.to_string(),
            mime_type,
            text: Some(content),
            blob: None,
        })
    }

    fn detect_mime_type(&self, path: &Path) -> String {
        match path.extension().and_then(|s| s.to_str()) {
            Some("rs") => "text/x-rust".to_string(),
            Some("toml") => "application/toml".to_string(),
            Some("json") => "application/json".to_string(),
            Some("md") => "text/markdown".to_string(),
            Some("txt") => "text/plain".to_string(),
            _ => "application/octet-stream".to_string(),
        }
    }

    fn parse_uri(&self, uri: &str) -> Result<PathBuf, Error> {
        // Remove "file:///" prefix
        let path = uri.strip_prefix("file:///")
            .ok_or_else(|| Error::InvalidUri(uri.to_string()))?;

        Ok(PathBuf::from(path))
    }
}
```

### Resource with Templates

```rust
#[derive(Clone)]
struct UserResource {
    db: Arc<Database>,
}

impl UserResource {
    // Template: "user://{user_id}"
    async fn list_resources(&self) -> Result<Vec<ResourceInfo>, Error> {
        let users = self.db.list_users().await?;

        let resources = users.into_iter().map(|user| ResourceInfo {
            uri: format!("user://{}", user.id),
            name: user.name.clone(),
            description: Some(format!("User profile for {}", user.name)),
            mime_type: Some("application/json".to_string()),
        }).collect();

        Ok(resources)
    }

    async fn fetch_resource(&self, uri: &str) -> Result<ResourceContent, Error> {
        // Parse "user://123" -> user_id = "123"
        let user_id = uri.strip_prefix("user://")
            .ok_or_else(|| Error::InvalidUri(uri.to_string()))?;

        let user = self.db.get_user(user_id).await?;
        let json = serde_json::to_string_pretty(&user)?;

        Ok(ResourceContent {
            uri: uri.to_string(),
            mime_type: "application/json".to_string(),
            text: Some(json),
            blob: None,
        })
    }
}
```

## Resource Patterns

### Pattern 1: Static Files

```rust
#[derive(Clone)]
struct DocumentationResource {
    docs_dir: PathBuf,
}

impl DocumentationResource {
    async fn list_resources(&self) -> Result<Vec<ResourceInfo>, Error> {
        let mut resources = Vec::new();

        for entry in walkdir::WalkDir::new(&self.docs_dir)
            .follow_links(true)
            .into_iter()
            .filter_map(|e| e.ok())
            .filter(|e| e.path().extension().map_or(false, |ext| ext == "md"))
        {
            let path = entry.path();
            let relative = path.strip_prefix(&self.docs_dir)?;

            resources.push(ResourceInfo {
                uri: format!("docs://{}", relative.display()),
                name: path.file_name()
                    .unwrap()
                    .to_string_lossy()
                    .to_string(),
                description: Some(format!("Documentation: {}", relative.display())),
                mime_type: Some("text/markdown".to_string()),
            });
        }

        Ok(resources)
    }
}
```

### Pattern 2: Database Records

```rust
#[derive(Clone)]
struct DatabaseResource {
    pool: PgPool,
}

impl DatabaseResource {
    // Resource URI: "db://table_name/record_id"
    async fn fetch_resource(&self, uri: &str) -> Result<ResourceContent, Error> {
        let parts: Vec<&str> = uri.strip_prefix("db://")
            .ok_or_else(|| Error::InvalidUri(uri.to_string()))?
            .split('/')
            .collect();

        if parts.len() != 2 {
            return Err(Error::InvalidUri(uri.to_string()));
        }

        let table = parts[0];
        let id = parts[1];

        // Query database
        let query = format!("SELECT * FROM {} WHERE id = $1", table);
        let row = sqlx::query(&query)
            .bind(id)
            .fetch_one(&self.pool)
            .await?;

        // Convert row to JSON
        let json = row_to_json(&row)?;

        Ok(ResourceContent {
            uri: uri.to_string(),
            mime_type: "application/json".to_string(),
            text: Some(json),
            blob: None,
        })
    }
}
```

### Pattern 3: API Integration

```rust
use reqwest::Client;

#[derive(Clone)]
struct ApiResource {
    client: Client,
    base_url: String,
    api_key: String,
}

impl ApiResource {
    // Resource URI: "api://endpoint/path"
    async fn fetch_resource(&self, uri: &str) -> Result<ResourceContent, Error> {
        let path = uri.strip_prefix("api://")
            .ok_or_else(|