# -----------------------------
async def main():
  async with stdio_server() as (read_stream, write_stream):
      await app.run(
          read_stream,
          write_stream,
          InitializationOptions(
              server_name="mcp-notes-server",
              server_version="0.1.0",
              capabilities=app.get_capabilities(
                  notification_options=NotificationOptions(),
                  experimental_capabilities={},
              ),
          ),
      )

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

Let's break it down into chunks:

### Tools

A tool is a function exposed by the server that an AI agent can call using `JSON-RPC`. Each tool includes its name, input parameters, output schema, and a description.

```python
#### TOOLS ####
@app.tool()
def write_note(slug: str, content: str) -> str:
  note_path = NOTES_DIR / f"{slug}.txt"
  note_path.write_text(content.strip(), encoding="utf-8")
  return f"Note '{slug}' saved."
```

### Resources

Resources are named, read-only data references addressable via URIs. Resources are used to load contextual read-only data into the MCP session.

```python
#### RESOURCES ####
@app.resource("note://{slug}")
def read_note(slug: str) -> str:
  note_path = NOTES_DIR / f"{slug}.txt"
  if not note_path.exists():
      return "Note not found."
  return note_path.read_text(encoding="utf-8")
```

### Prompts

Prompts are predefined message templates that servers expose to clients. When invoked with arguments, they return a list of messages (`messages[]`) that the client sends to the LLM to perform a specific task.

```python
#### PROMPTS ####
@app.prompt()
def suggest_note_prompt(topic: str) -> str:
  return f"""
      Write a short, thoughtful note for someone who needs advice about: {topic}
  """
```

### Roots

Roots are a set of scoped access boundaries provided by the client at handshake. Roots allow the server to limit the visibility of tools, resources, or data based on a given namespace.

```python
#### ROOTS ####
@app.tool()
def list_notes(root: str = None) -> list[str]:
  all_slugs = [f"note://{f.stem}" for f in NOTES_DIR.glob("*.txt")]
  if root:
      return [slug for slug in all_slugs if slug.startswith(root)]
  return all_slugs
```

### Transports

A transport defines the communication method the server uses to handle client connections. MCP supports multiple transports, including `stdio` for local execution and `http` for web-based deployment.

```python
async def main():
  async with stdio_server() as (read_stream, write_stream):
      await app.run(
          read_stream,
          write_stream,
          InitializationOptions(
              server_name="mcp-notes-server",
              server_version="0.1.0",
              capabilities=app.get_capabilities(
                  notification_options=NotificationOptions(),
                  experimental_capabilities={},
              ),
          ),
      )

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