Resources & Prompts — The Other Two MCP Primitives

# file_resource_server.py — MCP server exposing file system resources
from mcp.server.fastmcp import FastMCP
import pathlib

mcp = FastMCP("File Resources")


# ── CHUNK 1: Dynamic resource (URI template with {path} variable) ──
# WHAT: The {path} placeholder is extracted from any incoming URI matching
#       "file://{path}" and passed as the `path` argument to your function.
# WHY:  This lets the host request any file by URI — Claude can ask for
#       file:///workspace/config.yaml and your handler receives "workspace/config.yaml".
# GOTCHA: Path traversal! Always validate or restrict the path before reading.
@mcp.resource("file://{path}")
def read_file(path: str) -> str:
    """Read a file from the workspace by path.

    Returns the full text content of the file at the given path.
    Use this to pull source files, configs, or notes into context.
    """
    p = pathlib.Path(path)
    if not p.exists():
        raise FileNotFoundError(f"File not found: {path}")
    if not p.is_file():
        raise ValueError(f"Path is not a file: {path}")
    # Only allow files under current working directory (basic safety check)
    try:
        p.resolve().relative_to(pathlib.Path.cwd().resolve())
    except ValueError:
        raise PermissionError(f"Access denied: {path} is outside the workspace")
    return p.read_text(encoding="utf-8", errors="replace")


# ── CHUNK 2: Static resource (fixed URI, no template variables) ──
# WHAT: A concrete URI with no placeholders. The handler takes no extra args.
# WHY:  Use static resources for well-known data that has a stable identity —
#       a workspace summary, a README, a server configuration.
# GOTCHA: Static resources are still re-evaluated on every read request —
#         they are not cached unless the client implements caching.
@mcp.resource("file://workspace/summary")
def workspace_summary() -> str:
    """List all files in the current workspace directory.

    Returns a newline-separated list of relative file paths.
    """
    files = sorted(pathlib.Path(".").rglob("*"))
    file_list = [str(f) for f in files if f.is_file()]
    if not file_list:
        return "No files found in workspace."
    return "\n".join(file_list)


# ── CHUNK 3: JSON resource with explicit MIME type ──
# WHAT: Resources can return structured data. Declare mime_type="application/json"
#       so the host knows to treat the content as JSON, not plain text.
# WHY:  Some hosts (Claude Desktop) render JSON resources with syntax highlighting
#       or pretty-print them for the user.
@mcp.resource("workspace://stats", mime_type="application/json")
def workspace_stats() -> str:
    """Return statistics about the workspace as JSON."""
    import json, os
    files = list(pathlib.Path(".").rglob("*"))
    stats = {
        "total_files": sum(1 for f in files if f.is_file()),
        "total_dirs": sum(1 for f in files if f.is_dir()),
        "extensions": {},
    }
    for f in files:
        if f.is_file():
            ext = f.suffix.lower() or "(no ext)"
            stats["extensions"][ext] = stats["extensions"].get(ext, 0) + 1
    return json.dumps(stats, indent=2)


if __name__ == "__main__":
    mcp.run()

# code_review_prompts.py — MCP server exposing code review prompt templates
from mcp import types
from mcp.server.fastmcp import FastMCP

mcp = FastMCP("Code Review Prompts")


# ── CHUNK 1: Prompt with required and optional arguments ──
# WHAT: The `code` parameter is required (no default). `language` is optional
#       with a default of "python". FastMCP reads the type hints to build
#       the argument schema displayed in Claude Desktop's prompt picker.
# WHY:  Structured code reviews require domain-specific checklists.
#       Hardcoding them here ensures every security review covers all bases.
# GOTCHA: The f-string indentation inside the message text matters.
#         MCP preserves whitespace in message text — keep it clean.
@mcp.prompt()
def security_review(code: str, language: str = "python") -> list[types.Message]:
    """Generate a security-focused code review prompt.

    Asks Claude to review code for OWASP Top 10 vulnerabilities,
    with specific line references and remediation steps.
    """
    return [
        types.UserMessage(
            f"""Review the following {language} code for security vulnerabilities.

Focus on:
- SQL injection (parameterized queries? ORM misuse?)
- Cross-site scripting (XSS) if applicable
- Authentication and authorization flaws
- Sensitive data exposure (hardcoded secrets, logging PII)
- Insecure deserialization
- Known CVEs in dependencies if identifiable

```{language}
{code}
```

For each issue found:
1. Cite the specific line numbers
2. Explain why it is a vulnerability
3. Provide a corrected code snippet
4. Rate severity: Critical / High / Medium / Low

If no issues are found, state that explicitly and explain why the code is secure."""
        )
    ]


# ── CHUNK 2: Multi-turn prompt (user + assistant prefill) ──
# WHAT: A prompt can return more than one message — creating a conversation
#       fragment. Here we include an assistant prefill to guide Claude's
#       response format immediately.
# WHY:  Prefilling the assistant role forces Claude to continue in the
#       established format rather than starting with preamble.
@mcp.prompt()
def explain_error(error_message: str, context: str = "") -> list[types.Message]:
    """Generate a prompt to explain an error message with a fix.

    Provide the raw error output and optional surrounding context
    (file name, what you were doing) for a more precise explanation.
    """
    ctx_section = f"\n\nContext:\n{context}" if context.strip() else ""
    return [
        types.UserMessage(
            f"""Explain this error message and provide a concrete fix:{ctx_section}

```
{error_message}
```

Structure your response as:
1. What went wrong (plain English, one sentence)
2. Root cause (technical explanation)
3. How to fix it (exact code or commands)
4. How to prevent it in future"""
        )
    ]


# ── CHUNK 3: Prompt building a multi-step workflow ──
# WHAT: Prompts can encode entire multi-step workflows as a single message.
#       This one builds an architecture review prompt with all required
#       sections so Claude produces a structured, comparable output.
@mcp.prompt()
def architecture_review(
    system_description: str,
    scale: str = "startup",
    concerns: str = "scalability, security, cost",
) -> list[types.Message]:
    """Generate a system architecture review prompt.

    scale: startup | growth | enterprise
    concerns: comma-separated focus areas (e.g., 'scalability, security, cost')
    """
    concern_list = [c.strip() for c in concerns.split(",")]
    concerns_formatted = "\n".join(f"- {c}" for c in concern_list)
    return [
        types.UserMessage(
            f"""Review the following system architecture for a {scale}-stage company.

System description:
{system_description}

Evaluate specifically for:
{concerns_formatted}

Provide your assessment in this format:
## Strengths
## Risks
## Recommendations (prioritized)
## Quick wins (implementable in < 1 sprint)"""
        )
    ]


if __name__ == "__main__":
    mcp.run()

# notes_server.py — Complete MCP server with Tools + Resources + Prompts
from mcp import types
from mcp.server.fastmcp import FastMCP

mcp = FastMCP("Notes App")

# In-memory store: maps note_id -> {"title": str, "content": str, "tags": list[str]}
NOTES: dict[str, dict] = {}


# ══════════════ TOOLS ══════════════
# Tools = operations with side effects (write, delete, update)

@mcp.tool()
def save_note(title: str, content: str, tags: list[str] | None = None) -> dict:
    """Save a new note or overwrite an existing one.

    Returns the saved note's ID and total note count.
    """
    if not title.strip():
        raise ValueError("title must not be empty")
    if not content.strip():
        raise ValueError("content must not be empty")

    note_id = title.strip().lower().replace(" ", "-")
    # Remove non-alphanumeric characters except hyphens
    note_id = "".join(c for c in note_id if c.isalnum() or c == "-")

    NOTES[note_id] = {
        "title": title.strip(),
        "content": content.strip(),
        "tags": tags or [],
    }
    return {
        "success": True,
        "note_id": note_id,
        "total_notes": len(NOTES),
    }


@mcp.tool()
def delete_note(note_id: str) -> dict:
    """Delete a note by its ID.

    Returns success status and the deleted note's title.
    """
    if note_id not in NOTES:
        raise KeyError(f"Note '{note_id}' not found. Available: {list(NOTES.keys())}")
    deleted = NOTES.pop(note_id)
    return {"success": True, "deleted_title": deleted["title"]}


# ══════════════ RESOURCES ══════════════
# Resources = read-only data with stable URI addresses

@mcp.resource("note://{note_id}")
def read_note(note_id: str) -> str:
    """Read a single note by its ID.

    Returns the note's title, content, and tags as formatted text.
    """
    if note_id not in NOTES:
        raise KeyError(f"Note '{note_id}' not found. Available: {list(NOTES.keys())}")
    note = NOTES[note_id]
    tags_str = ", ".join(note["tags"]) if note["tags"] else "none"
    return f"# {note['title']}\n\nTags: {tags_str}\n\n{note['content']}"


@mcp.resource("note://index")
def list_notes() -> str:
    """List all saved notes with their IDs and titles."""
    if not NOTES:
        return "No notes saved yet."
    lines = [f"- {note_id}: {data['title']}" for note_id, data in sorted(NOTES.items())]
    return f"Saved notes ({len(NOTES)} total):\n" + "\n".join(lines)


# ══════════════ PROMPTS ══════════════
# Prompts = message templates the user invokes by name

@mcp.prompt()
def summarize_notes(focus: str = "key themes") -> list[types.Message]:
    """Summarize all saved notes.

    focus: what to emphasize — e.g., 'key themes', 'action items', 'decisions'
    """
    if not NOTES:
        return [types.UserMessage("There are no notes saved yet. Save some notes first using the save_note tool.")]

    notes_text = "\n\n---\n\n".join(
        f"**{data['title']}** (tags: {', '.join(data['tags']) or 'none'})\n{data['content']}"
        for note_id, data in sorted(NOTES.items())
    )
    return [
        types.UserMessage(
            f"""Here are all the saved notes. Please summarize them with a focus on: {focus}

{notes_text}

Provide:
1. A 2-3 sentence executive summary
2. The top 3-5 {focus}
3. Any action items or open questions you notice"""
        )
    ]


@mcp.prompt()
def find_connections(topic: str) -> list[types.Message]:
    """Find connections between notes related to a given topic."""
    if not NOTES:
        return [types.UserMessage(f"No notes saved yet. Add some notes first to find connections about '{topic}'.")]

    notes_text = "\n\n".join(
        f"[{note_id}] {data['title']}: {data['content'][:300]}..."
        if len(data["content"]) > 300
        else f"[{note_id}] {data['title']}: {data['content']}"
        for note_id, data in NOTES.items()
    )
    return [
        types.UserMessage(
            f"""Analyze the following notes and identify connections related to: {topic}

{notes_text}

For each connection found:
- Which notes are related
- What the connection is
- Why it matters for understanding '{topic}'"""
        )
    ]


if __name__ == "__main__":
    mcp.run()