How to Add Resources to Your FastMCP Server

# How to Add Resources to Your FastMCP Server

## What are MCP Resources?

In the Model Context Protocol (MCP), there are three main capabilities:

1. **Tools** - Functions that can be called (✅ you already have these)
2. **Resources** - Static or dynamic data that can be read
3. **Prompts** - Pre-defined prompt templates

**Resources** are like documents or data sources that AI models can access directly. They're perfect for:
- Configuration data
- Documentation
- Commonly accessed information
- Dynamic data that updates periodically

## Resource Types

### 1. **Static Resources**
Fixed content that doesn't change (e.g., documentation, guides)

### 2. **Dynamic Resources** 
Content that is generated or fetched on-demand (e.g., latest trending repos, your starred repos)

## How to Add Resources to Your Server

### Basic Syntax

```python
from fastmcp import FastMCP

mcp = FastMCP("Your Server Name")

# Static Resource
@mcp.resource("resource://your-server/your-resource-name")
async def get_static_resource() -> str:
    """Description of what this resource provides."""
    return "Your resource content here"

# Dynamic Resource
@mcp.resource("resource://your-server/dynamic/{param}")
async def get_dynamic_resource(param: str) -> str:
    """Dynamic resource that uses parameters."""
    return f"Content based on {param}"
```

## Example Resources for Your GitHub Crawler

Here are some useful resources you can add:

### 1. **Popular Python Repos** (Dynamic)
```python
@mcp.resource("resource://github-crawler/trending/python")
async def get_trending_python_repos() -> str:
    """Get currently trending Python repositories on GitHub."""
    params = {
        "q": "language:python",
        "sort": "stars",
        "order": "desc",
        "per_page": 10
    }
    data = await _make_github_request("/search/repositories", params)
    
    # Format nicely
    result = "# Top 10 Python Repositories\n\n"
    for repo in data.get("items", []):
        result += f"## {repo.get('full_name')}\n"
        result += f"⭐ {repo.get('stargazers_count')} | "
        result += f"🍴 {repo.get('forks_count')}\n"
        result += f"{repo.get('description', 'No description')}\n\n"
    
    return result
```

### 2. **GitHub Rate Limit Status** (Dynamic)
```python
@mcp.resource("resource://github-crawler/rate-limit")
async def get_rate_limit_status() -> str:
    """Get current GitHub API rate limit status."""
    data = await _make_github_request("/rate_limit")
    
    core = data.get("resources", {}).get("core", {})
    search = data.get("resources", {}).get("search", {})
    
    return f"""# GitHub API Rate Limit Status

## Core API
- Limit: {core.get('limit')}
- Remaining: {core.get('remaining')}
- Resets at: {core.get('reset')}

## Search API  
- Limit: {search.get('limit')}
- Remaining: {search.get('remaining')}
- Resets at: {search.get('reset')}
"""
```

### 3. **Server Documentation** (Static)
```python
@mcp.resource("resource://github-crawler/docs/overview")
async def get_server_docs() -> str:
    """Get comprehensive server documentation."""
    return """# GitHub Crawler MCP Server Documentation

## Available Tools

### Repository Search
- search_repositories: Search for repositories
- get_repository_details: Get detailed repo info
- list_user_repositories: List all repos for a user

### Content Access
- get_repository_contents: Browse files and directories
- get_file_content: Download specific files
- get_repository_readme: Get README content

### Analysis
- get_repository_structure: Get complete directory tree
- get_repository_languages: Analyze programming languages
- list_repository_commits: View commit history

### Issues & PRs
- list_repository_issues: Browse issues
- list_pull_requests: View pull requests

## Usage Tips

1. Always specify owner and repo parameters
2. Use GitHub Personal Access Token for private repos
3. Rate limits: 5,000/hour with token, 60/hour without

## Example Queries

- "Show me the README for jlowin/fastmcp"
- "List popular Python web frameworks"
- "Get the structure of the React repository"
"""
```

### 4. **Awesome Lists** (Static)
```python
@mcp.resource("resource://github-crawler/awesome/ai")
async def get_awesome_ai_repos() -> str:
    """Curated list of awesome AI repositories."""
    return """# Awesome AI Repositories

## Large Language Models
- openai/openai-python - Official OpenAI Python library
- langchain-ai/langchain - Building applications with LLMs
- anthropics/anthropic-sdk-python - Anthropic Claude SDK

## UI/Frameworks
- vercel/ai - AI SDK for TypeScript
- jlowin/fastmcp - Fast MCP server framework

## Research
- openai/gpt-4 - GPT-4 Technical Report
- facebookresearch/llama - LLaMA models
"""
```

### 5. **Your Starred Repos** (Dynamic - requires authentication)
```python
@mcp.resource("resource://github-crawler/user/starred")
async def get_my_starred_repos() -> str:
    """Get repositories you've starred (requires GitHub token)."""
    if not GITHUB_TOKEN:
        return "Error: GitHub token required to access starred repositories"
    
    endpoint = "/user/starred"
    params = {"per_page": 20, "sort": "updated"}
    
    data = await _make_github_request(endpoint, params)
    
    result = "# Your Starred Repositories\n\n"
    for repo in data:
        result += f"## {repo.get('full_name')}\n"
        result += f"{repo.get('description', 'No description')}\n"
        result += f"Language: {repo.get('language', 'N/A')} | "
        result += f"⭐ {repo.get('stargazers_count')}\n\n"
    
    return result
```

### 6. **Quick Reference** (Static)
```python
@mcp.resource("resource://github-crawler/reference/api")
async def get_api_reference() -> str:
    """Quick API reference for common GitHub operations."""
    return """# GitHub API Quick Reference

## Search Qualifiers

### Language
- `language:python` - Python repositories
- `language:javascript` - JavaScript repositories

### Size
- `size:>1000` - Larger than 1MB
- `size:<100` - Smaller than 100KB

### Stars
- `stars:>1000` - More than 1000 stars
- `stars:100..500` - Between 100 and 500 stars

### Topics
- `topic:machine-learning`
- `topic:web-framework`

### Organization
- `org:facebook` - Facebook repos
- `user:octocat` - User repos

## Example Queries

```
fastmcp language:python stars:>100
machine learning topic:ai language:python
react framework stars:>10000
```
"""
```

## Adding Resources to Your Server

To add these resources to your `github_crawler_server.py`:

1. **Add resources after your tools** (before `if __name__ == "__main__"`):

```python
# ... your existing tools ...

# ============= RESOURCES =============

@mcp.resource("resource://github-crawler/trending/python")
async def get_trending_python_repos() -> str:
    """Get currently trending Python repositories on GitHub."""
    # implementation here
    pass

@mcp.resource("resource://github-crawler/rate-limit")
async def get_rate_limit_status() -> str:
    """Get current GitHub API rate limit status."""
    # implementation here
    pass

# ... more resources ...

# Run the server
if __name__ == "__main__":
    mcp.run()
```

2. **Deploy to FastMCP Cloud** - Resources will automatically appear in the resources section

3. **Use in ChatGPT** - The AI can now read these resources directly

## Testing Resources Locally

```python
# test_resources.py
import asyncio
from github_crawler_server import mcp

async def test_resources():
    # List all resources
    resources = await mcp.list_resources()
    print("Available resources:")
    for resource in resources:
        print(f"  - {resource.uri}: {resource.description}")
    
    # Read a specific resource
    content = await mcp.read_resource("resource://github-crawler/trending/python")
    print("\nResource content:")
    print(content)

if __name__ == "__main__":
    asyncio.run(test_resources())
```

## Best Practices

1. **Use descriptive URIs**: `resource://server-name/category/specific-item`
2. **Add good descriptions**: Help AI understand what the resource contains
3. **Return formatted content**: Use markdown for better readability
4. **Cache expensive resources**: Use FastMCP's caching if data doesn't change often
5. **Handle errors gracefully**: Return helpful error messages

## Resources vs Tools

**Use Resources when:**
- Data is read-only
- Content is relatively static or changes infrequently
- You want AI to access information quickly
- You have reference documentation

**Use Tools when:**
- You need to perform actions
- Parameters are required for each request
- The operation has side effects
- You need complex logic or filtering

## Next Steps

1. Choose which resources make sense for your use case
2. Add them to your `github_crawler_server.py`
3. Test locally
4. Deploy to FastMCP Cloud
5. Use them with ChatGPT or Claude!