### Manual Setup and Server Start

Source: https://github.com/dicklesworthstone/mcp_agent_mail/blob/main/README.md

Steps to manually set up the MCP Agent Mail server from a cloned repository, including creating a virtual environment, installing dependencies, and running the server.

```bash
git clone https://github.com/Dicklesworthstone/mcp_agent_mail
cd mcp_agent_mail

# Create a Python 3.14 virtual environment and install dependencies
# Note: If you have an older uv version, run `uv self update` first
uv python install 3.14
uv venv -p 3.14
source .venv/bin/activate
uv sync

# Detect installed coding agents, integrate, and start the MCP server on port 8765
scripts/automatically_detect_all_installed_coding_agents_and_install_mcp_agent_mail_in_all.sh

# Later, to run the MCP server again with the same token
scripts/run_server_with_token.sh
```

--------------------------------

### One-line Installer for MCP Agent Mail

Source: https://github.com/dicklesworthstone/mcp_agent_mail/blob/main/README.md

This command installs uv, jq, sets up a Python virtual environment, installs dependencies, configures agent tools, and starts the MCP HTTP server. It also creates helper scripts and shell aliases for easy access. Use flags like --yes for non-interactive installation.

```bash
curl -fsSL "https://raw.githubusercontent.com/Dicklesworthstone/mcp_agent_mail/main/scripts/install.sh?$(date +%s)" | bash -s -- --yes
```

--------------------------------

### uv Installation and Usage Instructions

Source: https://github.com/dicklesworthstone/mcp_agent_mail/blob/main/third_party_docs/PYTHON_FASTMCP_BEST_PRACTICES.md

Provides step-by-step instructions for installing dependencies, setting up the environment, and running the MCP server using uv.

```bash
# 1. Create virtual environment: uv venv --python 3.13
# 2. Activate: source .venv/bin/activate
# 3. Install: uv sync --all-extras
# 4. Set up environment: cp .env.example .env && # Edit .env
# 5. Initialize system: smartedgar setup
# 6. Run MCP server: smartedgar run-server
#    # Or for HTTP transport: smartedgar run-server --transport http
# 7. Other commands: smartedgar --help
```

--------------------------------

### Run FastMCP Server Locally via CLI

Source: https://github.com/dicklesworthstone/mcp_agent_mail/blob/main/third_party_docs/fastmcp_distilled_docs.md

Examples of using the `fastmcp run` command to start a local server. It shows how to specify the server file, transport type, and host/port.

```bash
# Run a local server with HTTP transport on port 9000
fastmcp run my_server.py --transport http --port 9000

# Proxy a remote server, making it available locally via STDIO
fastmcp run https://remote-server.com/mcp/
```

--------------------------------

### uv Tool Installation and Execution

Source: https://github.com/dicklesworthstone/mcp_agent_mail/blob/main/third_party_docs/PYTHON_FASTMCP_BEST_PRACTICES.md

Demonstrates how to use uv to install and run linters/formatters like Ruff in isolation.

```bash
uv tool install ruff
uv tool run ruff check .
```

--------------------------------

### Start Session Macro

Source: https://github.com/dicklesworthstone/mcp_agent_mail/blob/main/docs/planning/PLAN_TO_NON_DISRUPTIVELY_INTEGRATE_WITH_THE_GIT_WORKTREE_APPROACH.md

This macro starts a new session and returns project details, potentially including a product UID.

```python
macro_start_session(...)
```

--------------------------------

### Install FastMCP

Source: https://github.com/dicklesworthstone/mcp_agent_mail/blob/main/third_party_docs/fastmcp_distilled_docs.md

Standard installation methods using package managers.

```bash
# Using uv
uv pip install fastmcp
```

```bash
# Using pip
pip install fastmcp
```

--------------------------------

### Command: install

Source: https://github.com/dicklesworthstone/mcp_agent_mail/blob/main/third_party_docs/fastmcp_distilled_docs.md

Installs a local server into a supported MCP client application, automating the creation of client configuration files.

```APIDOC
## Command: install

### Description
Installs a local server into a supported MCP client application. This command automates the creation of the client's configuration files.

### Usage
`fastmcp install [CLIENT_TARGET] [OPTIONS] SERVER_SPEC`

### Client Targets
- `claude-code`
- `claude-desktop`
- `cursor`
- `mcp-json`

### Dependency Management
Same as `dev` command (`--with`, `--with-editable`).

### Environment Variables
- `--env-var, -v KEY=VALUE`: Pass an environment variable.
- `--env-file, -f <path>`: Load variables from a `.env` file.

### Key Requirement
The server runs in a highly isolated environment managed by the client application. `uv` must be installed and in the system `PATH`. All dependencies and environment variables **must** be explicitly provided.

#### Target: `claude-code`
Installs the server using the `claude mcp add` command.

##### Example
```bash
fastmcp install claude-code ./servers/api_server.py \
  --name "MyAPIServer" \
  --with requests \
  --env-file .env
```

#### Target: `claude-desktop`
Directly modifies the `claude_desktop_config.json` file.

##### Example
```bash
fastmcp install claude-desktop ./servers/local_tool.py --with pandas
```

#### Target: `cursor`
Generates a `cursor://` deeplink and opens it, prompting the user to confirm installation within the Cursor application.

##### Example
```bash
fastmcp install cursor ./servers/code_gen_server.py --with-editable ./my_local_library
```

#### Target: `mcp-json`
Generates a standard `mcpServers` JSON configuration object and prints it to stdout. This can be used for unsupported clients or for scripting.

##### Options
- `--copy`: Copies the JSON to the clipboard instead of printing.

##### Examples
```bash
# Generate JSON config and save to a file
fastmcp install mcp-json my_server.py > config.json

# Generate and copy to clipboard
fastmcp install mcp-json my_server.py --copy
```
```

--------------------------------

### Docker Buildx Builder Setup

Source: https://github.com/dicklesworthstone/mcp_agent_mail/blob/main/README.md

Create and select a Docker Buildx builder instance. This is a one-time setup for multi-architecture builds.

```bash
# Create and select a builder (once)
docker buildx create --use --name mcp-builder || docker buildx use mcp-builder
```

--------------------------------

### Install FastMCP for Development

Source: https://github.com/dicklesworthstone/mcp_agent_mail/blob/main/third_party_docs/fastmcp_distilled_docs.md

Clone the repository and set up the development environment.

```bash
git clone https://github.com/jlowin/fastmcp.git
cd fastmcp
uv sync
```

--------------------------------

### Install Guard Utility

Source: https://github.com/dicklesworthstone/mcp_agent_mail/blob/main/docs/planning/PLAN_TO_NON_DISRUPTIVELY_INTEGRATE_WITH_THE_GIT_WORKTREE_APPROACH.md

Installs a git pre-push guard for a given project. Optionally enables prepush checks.

```python
install_guard(project_key: str, repo_path: str, install_prepush?: bool)
```

--------------------------------

### Install uv Package Manager

Source: https://github.com/dicklesworthstone/mcp_agent_mail/blob/main/README.md

Installs the uv package manager. Ensure uv is in your PATH after installation.

```bash
curl -LsSf https://astral.sh/uv/install.sh | sh
export PATH="$HOME/.local/bin:$PATH"
```

--------------------------------

### Start the MCP Agent Mail Server

Source: https://github.com/dicklesworthstone/mcp_agent_mail/blob/main/SKILL.md

Commands to launch the server using the installed alias or the manual script path.

```bash
# Quickest way (alias added during install)
am

# Or manually
cd ~/projects/mcp_agent_mail
./scripts/run_server_with_token.sh
```

--------------------------------

### Install Pre-commit and Pre-push Guards

Source: https://github.com/dicklesworthstone/mcp_agent_mail/blob/main/docs/planning/PLAN_TO_NON_DISRUPTIVELY_INTEGRATE_WITH_THE_GIT_WORKTREE_APPROACH.md

Install both pre-commit and pre-push guards for agent mail by adding the --prepush flag to the install command.

```bash
mcp-agent-mail guard install <project-slug-or-human-key> . --prepush
```

--------------------------------

### Install with Local Script and Custom Port

Source: https://github.com/dicklesworthstone/mcp_agent_mail/blob/main/README.md

Installs the agent using a local installation script, allowing for a custom HTTP port to be specified. This method is useful for offline installations or custom build processes.

```bash
./scripts/install.sh --port 9000 --yes
```

--------------------------------

### uv Free-threaded Python Installation

Source: https://github.com/dicklesworthstone/mcp_agent_mail/blob/main/third_party_docs/PYTHON_FASTMCP_BEST_PRACTICES.md

Shows how to install a free-threaded (GIL-less) CPython version using uv for potential parallelism benefits.

```bash
uv python install 3.13.0-ft
```

--------------------------------

### Resource URL Examples

Source: https://github.com/dicklesworthstone/mcp_agent_mail/blob/main/SKILL.md

Provides examples of resource URLs for accessing various types of data, such as inbox messages, threads, file reservations, and project/agent information.

```shell
resource://inbox/{agent}?project=<path>&limit=20&include_bodies=true
```

```shell
resource://thread/{thread_id}?project=<path>&include_bodies=true
```

```shell
resource://message/{id}?project=<path>
```

```shell
resource://file_reservations/{slug}?active_only=true
```

```shell
resource://project/{slug}
```

```shell
resource://projects
```

```shell
resource://agents/{project_key}
```

--------------------------------

### Install MCP server for Cursor

Source: https://github.com/dicklesworthstone/mcp_agent_mail/blob/main/third_party_docs/fastmcp_distilled_docs.md

Generates a deeplink to trigger installation within the Cursor application.

```bash
fastmcp install cursor ./servers/code_gen_server.py --with-editable ./my_local_library
```

--------------------------------

### Run a development server with dependencies

Source: https://github.com/dicklesworthstone/mcp_agent_mail/blob/main/third_party_docs/fastmcp_distilled_docs.md

Starts a server in an isolated environment using the MCP Inspector for debugging.

```bash
# Run a dev server that depends on pandas
fastmcp dev my_data_server.py --with pandas
```

--------------------------------

### Install Pre-commit Guard into a Repository

Source: https://github.com/dicklesworthstone/mcp_agent_mail/blob/main/README.md

Installs the pre-commit guard into a specified local repository. Requires the project key and the absolute path to the code repository.

```bash
uv run python -m mcp_agent_mail.cli guard install /abs/path/backend /abs/path/backend
```

--------------------------------

### macro_start_session

Source: https://github.com/dicklesworthstone/mcp_agent_mail/blob/main/README.md

Orchestrates a session start, including project ensuring, agent registration, optional file reservation, and inbox fetching.

```APIDOC
## macro_start_session

### Description
Orchestrates ensure→register→optional file reservation→inbox fetch.

### Method
`macro_start_session(human_key: str, program: str, model: str, task_description?: str, agent_name?: str, registration_token?: str, file_reservation_paths?: list[str], file_reservation_reason?: str, file_reservation_ttl_seconds?: int, inbox_limit?: int)`

### Parameters
#### Path Parameters
- **human_key** (str) - Required - The human-readable key for the project.
- **program** (str) - Required - The program associated with the agent.
- **model** (str) - Required - The model used by the agent.
#### Optional Parameters
- **task_description** (str) - Optional - A description of the agent's task.
- **agent_name** (str) - Optional - The name of the agent.
- **registration_token** (str) - Optional - Token for registration.
- **file_reservation_paths** (list[str]) - Optional - Paths for file reservation.
- **file_reservation_reason** (str) - Optional - Reason for file reservation.
- **file_reservation_ttl_seconds** (int) - Optional - Time-to-live for file reservation in seconds.
- **inbox_limit** (int) - Optional - The limit for fetching inbox messages.

### Returns
`{project, agent, file_reservations, inbox}`
```

--------------------------------

### Message File Format Example

Source: https://github.com/dicklesworthstone/mcp_agent_mail/blob/main/README.md

This example shows the structure of a message file, including GitHub-Flavored Markdown with JSON frontmatter and attachment references. The JSON frontmatter contains metadata about the message.

```markdown
---
---
---
{
  "id": 1234,
  "thread_id": "TKT-123",
  "project": "/abs/path/backend",
  "project_slug": "backend-abc123",
  "from": "GreenCastle",
  "to": ["BlueLake"],
  "cc": [],
  "created": "2025-10-23T15:22:14Z",
  "importance": "high",
  "ack_required": true,
  "attachments": [
    {"type": "file", "media_type": "image/webp", "path": "projects/backend-abc123/attachments/2a/2a6f.../diagram.webp"}
  ]
}
---

# Build plan for /api/users routes

... body markdown ...
```

--------------------------------

### Start MCP Agent Mail Server

Source: https://github.com/dicklesworthstone/mcp_agent_mail/blob/main/README.md

Run this command from any directory to start the MCP Agent Mail server. It automatically changes to the correct directory, runs the startup script, and loads the bearer token from .env.

```bash
am
```

--------------------------------

### Message File Format Example

Source: https://github.com/dicklesworthstone/mcp_agent_mail/blob/main/docs/planning/project_idea_and_guide.md

Illustrates the structure of a message file, including YAML frontmatter with metadata and the main content.

```YAML
---
id: "msg_20251023_7b3dc3a7"
thread_id: "TKT-123"
project: "backend-repo"
from: "GreenCastle"
to: ["RedCat","BlueLake"]
cc: []
created: "2025-10-23T15:22:14Z"
importance: "high"
ack_required: true
attachments:
  - type: "file"
    path: "../../attachments/2a/2a6f.../diagram.webp"
  # or:
  - type: "inline"
    media_type: "image/webp"
    data_base64: "<very-compressed-base64>"
---

# Build plan for /api/users routes

...
```

--------------------------------

### Running with Gunicorn

Source: https://github.com/dicklesworthstone/mcp_agent_mail/blob/main/third_party_docs/fastmcp_distilled_docs.md

Command to start the FastMCP server using Gunicorn with Uvicorn workers for production traffic.

```bash
# Start Gunicorn with 4 Uvicorn worker processes, listening on port 8000
gunicorn -w 4 -k uvicorn.workers.UvicornWorker my_production_server:app -b 0.0.0.0:8000
```

--------------------------------

### Defer Alpine.js Loading

Source: https://github.com/dicklesworthstone/mcp_agent_mail/blob/main/src/mcp_agent_mail/viewer_assets/index.html

Provides a function to defer the initialization of Alpine.js, allowing for custom setup before Alpine starts.

```javascript
window.deferLoadingAlpine = function (alpineInit) {
  window.__alpineStart = alpineInit;
}
```

--------------------------------

### Bootstrap a Session with macro_start_session

Source: https://github.com/dicklesworthstone/mcp_agent_mail/blob/main/SKILL.md

Initializes a project, registers an agent identity, reserves files, and retrieves the inbox in a single call.

```text
macro_start_session(
  human_key="/abs/path/to/project",
  program="claude-code",
  model="opus-4.5",
  task_description="Implementing auth module"
)
```

--------------------------------

### Example: Clarification Message

Source: https://github.com/dicklesworthstone/mcp_agent_mail/blob/main/README.md

Use this format to provide clarification on ongoing tasks or design decisions, guiding agents on the preferred approach.

```markdown
Subject: Clarification on API design approach

I see you're debating REST vs. GraphQL in thread #234.

Go with REST for now because:
- Our frontend team has more REST experience
- GraphQL adds complexity we don't need yet
- We can always add GraphQL later if needed

Resume the API implementation with REST.
```

--------------------------------

### Launch Server with Token

Source: https://github.com/dicklesworthstone/mcp_agent_mail/blob/main/README.md

Recommended method to launch the server. Ensure you have the necessary token. Opens the Web UI at http://127.0.0.1:8765/mail.

```bash
scripts/run_server_with_token.sh
# then open http://127.0.0.1:8765/mail
```

--------------------------------

### Configure Custom Port via CLI

Source: https://github.com/dicklesworthstone/mcp_agent_mail/blob/main/README.md

After installation, you can change the server port using this CLI command. This example sets the port to 9000.

```bash
uv run python -m mcp_agent_mail.cli config set-port 9000
```

--------------------------------

### Customize API Route to MCP Component Mapping

Source: https://github.com/dicklesworthstone/mcp_agent_mail/blob/main/third_party_docs/fastmcp_distilled_docs.md

Define rules for converting API routes to specific MCP component types (TOOL, RESOURCE, RESOURCE_TEMPLATE, EXCLUDE) using RouteMap objects. This example shows how to map GET requests with path parameters to ResourceTemplates, other GET requests to Resources, and exclude admin endpoints.

```python
from fastmcp.server.openapi import RouteMap, MCPType

mcp = FastMCP.from_openapi(
    openapi_spec=spec,
    client=client,
    route_maps=[
        # Rule 1: GET requests with path params (e.g., /users/{id}) become ResourceTemplates
        RouteMap(methods=["GET"], pattern=r".*\{.*\}.*", mcp_type=MCPType.RESOURCE_TEMPLATE),
        
        # Rule 2: All other GET requests become Resources
        RouteMap(methods=["GET"], mcp_type=MCPType.RESOURCE),
        
        # Rule 3: Exclude all admin endpoints
        RouteMap(pattern=r"^/admin/.*",
```

--------------------------------

### Initialize Tutorial Manager

Source: https://github.com/dicklesworthstone/mcp_agent_mail/blob/main/src/mcp_agent_mail/templates/base.html

Manages the user tutorial flow, including step progression, action tracking, and persistence of tutorial completion and progress via localStorage. It also handles event listeners for restarting and user actions.

```javascript
function tutorialManager() {
  return {
    isActive: false,
    currentStep: 0,
    highlightElement: false,
    spotlightX: 0,
    spotlightY: 0,
    spotlightSize: 150,
    completedActions: [],
    // Cleanup tracking
    eventListeners: [],
    animationCleanup: null,
    steps: [
      { title: 'Welcome to Agent Mail', icon: 'mail', actions: [] },
      { title: 'What are Projects?', icon: 'folder', actions: ['viewed_projects'] },
      { title: 'Related Projects', icon: 'git-branch', actions: ['learned_siblings'] },
      { title: 'What are Agents?', icon: 'bot', actions: ['learned_agents'] },
      { title: 'How Agents Communicate', icon: 'message-square', actions: ['learned_messages'] },
      { title: 'Human Overseer', icon: 'shield-alert', actions: ['learned_overseer'] },
      { title: 'File Reservations', icon: 'file-lock', actions: ['learned_reservations'] },
      { title: 'Powerful Features', icon: 'sparkles', actions: ['learned_features'] },
      { title: 'You\'re All Set!', icon: 'check-circle', actions: [] }
    ],
    // Computed progress with divide-by-zero protection
    get progress() {
      if (this.steps.length === 0) return 0;
      return ((this.currentStep + 1) / this.steps.length) * 100;
    },
    init() {
      // Check if user has seen tutorial
      const hasSeenTutorial = localStorage.getItem('agentmail_tutorial_completed');
      // Load completed actions
      const savedActions = localStorage.getItem('agentmail_tutorial_actions');
      if (savedActions) {
        try {
          this.completedActions = JSON.parse(savedActions);
        } catch (e) {
          this.completedActions = [];
        }
      }
      if (!hasSeenTutorial) {
        // Show tutorial on first visit (with slight delay for page to render)
        setTimeout(() => {
          this.isActive = true;
          this.$nextTick(() => lucide.createIcons());
        }, 800);
      }
      // Listen for restart event (track for cleanup)
      const restartHandler = () => {
        this.restart();
      };
      window.addEventListener('restart-tutorial', restartHandler);
      this.eventListeners.push({ target: window, event: 'restart-tutorial', handler: restartHandler });
      // Listen for user actions
      this.trackUserActions();
    },
    destroy() {
      // Clean up all event listeners
      this.eventListeners.forEach(({ target, event, handler }) => {
        target.removeEventListener(event, handler);
      });
      this.eventListeners = [];
      // Clean up animation timers
      if (this.animationCleanup) {
        this.animationCleanup();
        this.animationCleanup = null;
      }
    },
    next() {
      if (this.currentStep < this.steps.length - 1) {
        // Mark current step actions as complete
        const currentActions = this.steps[this.currentStep].actions;
        currentActions.forEach(action => {
          if (!this.completedActions.includes(action)) {
            this.completedActions.push(action);
          }
        });
        this.saveProgress();
        this.currentStep++;
        this.$nextTick(() => lucide.createIcons());
      } else {
        this.complete();
      }
    },
    previous() {
      if (this.currentStep > 0) {
        this.currentStep--;
        this.$nextTick(() => lucide.createIcons());
      }
    },
    skip() {
      this.complete();
    },
    complete() {
      // Clean up any running animations
      if (this.animationCleanup) {
        this.animationCleanup();
        this.animationCleanup = null;
      }
      localStorage.setItem('agentmail_tutorial_completed', 'true');
      this.saveProgress();
      this.isActive = false;
      window.showToast('Tutorial completed! Press ? for keyboard shortcuts anytime.', 'success', 4000);
    },
    restart() {
      this.currentStep = 0;
      this.isActive = true;
      this.completedActions = [];
      localStorage.removeItem('agentmail_tutorial_completed');
      this.$nextTick(() => lucide.createIcons());
    },
    saveProgress() {
      localStorage.setItem('agentmail_tutorial_actions', JSON.stringify(this.completedActions));
    },
    // Track user actions to detect when they actually try features
    trackUserActions() {
      // Detect command palette usage (track for cleanup)
      const keydownHandler = (e) => {
        if ((e.metaKey || e.ctrlKey) && e.key === 'k') {
          this.markActionComplete('used_command_palette');
        }
        if (e.shiftKey && e.key === '?') {
          th
```

--------------------------------

### Beads Workflow Example

Source: https://github.com/dicklesworthstone/mcp_agent_mail/blob/main/SKILL.md

Illustrates a typical workflow when using Beads for task management, including picking work, reserving files, announcing start, updating progress, and completing tasks. Identifiers like 'bd-###' are used consistently across different operations.

```shell
1. Pick ready work:     bd ready --json → choose bd-123
2. Reserve files:       file_reservation_paths(..., reason="bd-123")
3. Announce start:      send_message(..., thread_id="bd-123", subject="[bd-123] Starting...")
4. Work and update:     Reply in thread with progress
5. Complete:            bd close bd-123
                        release_file_reservations(...)
                        send_message(..., subject="[bd-123] Completed")
```

--------------------------------

### Instantiate a FastMCP Server

Source: https://github.com/dicklesworthstone/mcp_agent_mail/blob/main/third_party_docs/fastmcp_distilled_docs.md

Create a server instance with optional LLM guidance instructions.

```python
from fastmcp import FastMCP

# Basic server with a name
mcp = FastMCP(name="MyAssistantServer")

# Server with instructions to guide the LLM
mcp_with_instructions = FastMCP(
    name="HelpfulAssistant",
    instructions="""
    This server provides data analysis tools.
    Use the `get_average` tool to analyze numerical data.
    Access configuration via the `resource://config` resource.
    """
)
```

--------------------------------

### Verify FastMCP Installation

Source: https://github.com/dicklesworthstone/mcp_agent_mail/blob/main/third_party_docs/fastmcp_distilled_docs.md

Check the installed version and environment details.

```bash
$ fastmcp version

FastMCP version:   2.10.5
MCP version:       1.10.0
Python version:    3.12.2
Platform:          ...
FastMCP root path: ...
```

--------------------------------

### Instantiate and Run FastMCP Client

Source: https://github.com/dicklesworthstone/mcp_agent_mail/blob/main/third_party_docs/fastmcp_distilled_docs.md

Demonstrates the asynchronous lifecycle of a FastMCP client using a context manager.

```python
import asyncio
from fastmcp import Client

async def main():
    # The client infers the transport from the source
    async with Client("my_server.py") as client:
        # Interactions happen inside the context block
        is_alive = await client.ping()
        print(f"Server is alive: {is_alive}")

asyncio.run(main())
```

--------------------------------

### Install mcp_agent_mail

Source: https://github.com/dicklesworthstone/mcp_agent_mail/blob/main/SKILL.md

Installation scripts for the project, including port configuration options.

```bash
# One-liner (recommended)
curl -fsSL "https://raw.githubusercontent.com/Dicklesworthstone/mcp_agent_mail/main/scripts/install.sh?$(date +%s)" | bash -s -- --yes

# Custom port
curl -fsSL ... | bash -s -- --port 9000 --yes

# Change port after installation
uv run python -m mcp_agent_mail.cli config set-port 9000
```

--------------------------------

### Launch Interactive Deployment Wizard via CLI

Source: https://github.com/dicklesworthstone/mcp_agent_mail/blob/main/README.md

Starts the interactive wizard for exporting and deploying projects to GitHub Pages or Cloudflare Pages. This is the recommended method.

```bash
uv run python -m mcp_agent_mail.cli share wizard
```

--------------------------------

### Run Server Manually with UV

Source: https://github.com/dicklesworthstone/mcp_agent_mail/blob/main/README.md

Alternative advanced method to launch the server using UV. Allows manual configuration of host and port.

```bash
uv run python -m mcp_agent_mail.http --host 127.0.0.1 --port 8765
```

--------------------------------

### resource://config/environment

Source: https://github.com/dicklesworthstone/mcp_agent_mail/blob/main/README.md

Inspect server settings. Appending `?format=toon` returns `{format:"toon", data:"<TOON>", meta:{...}}`.

```APIDOC
## GET resource://config/environment

### Description
Retrieves server configuration details including environment variables and database connection information.

### Method
GET

### Endpoint
/config/environment

### Parameters
#### Query Parameters
- **format** (string) - Optional - Specifies the output format. Supported values include `json` and `toon`.

### Response
#### Success Response (200)
- **environment** (object) - Server environment details.
- **database_url** (string) - The connection URL for the database.
- **http** (object) - HTTP server configuration.

### Response Example
```json
{
  "environment": {
    "NODE_ENV": "production"
  },
  "database_url": "postgres://user:password@host:port/database",
  "http": {
    "port": 8080
  }
}
```
```

--------------------------------

### Show Interactive Tutorial Action

Source: https://github.com/dicklesworthstone/mcp_agent_mail/blob/main/src/mcp_agent_mail/templates/base.html

Action to start the interactive tutorial. It closes the current panel and uses `setTimeout` to restart the tutorial after a short delay.

```javascript
() => { this.close(); setTimeout(() => window.restartTutorial(), 200); }
```

--------------------------------

### Registering Methods as Tools

Source: https://github.com/dicklesworthstone/mcp_agent_mail/blob/main/third_party_docs/fastmcp_distilled_docs.md

Demonstrates the recommended pattern for registering instance, class, and static methods as FastMCP tools.

```APIDOC
## Registering Methods as Tools

### Description
Directly applying FastMCP decorators to instance or class methods is not recommended because the decorator captures the unbound method, exposing `self` or `cls` as a parameter to the LLM. The correct pattern is to register the bound method after class/instance creation.

### Example
```python
from fastmcp import FastMCP

mcp = FastMCP()

class MyAPIServer:
    def __init__(self, api_key: str):
        self.api_key = api_key

    def get_data(self, item_id: str) -> dict:
        # Instance method uses `self.api_key`
        return {"data": f"data for {item_id}"}

    @classmethod
    def get_server_info(cls) -> dict:
        return {"name": cls.__name__}

    @staticmethod
    def utility_function(a: int, b: int) -> int:
        return a + b

# --- Registration ---

# Instance method: create instance, then register the bound method
api_instance = MyAPIServer(api_key="secret")
mcp.tool(api_instance.get_data)

# Class method: register directly from the class
mcp.tool(MyAPIServer.get_server_info)

# Static method: register directly from the class
mcp.tool(MyAPIServer.utility_function)
```
```

--------------------------------

### Serve bundle with custom port and auto-open browser

Source: https://github.com/dicklesworthstone/mcp_agent_mail/blob/main/README.md

Serves the bundle locally on a custom port (e.g., 8080) and automatically opens the default web browser to the preview URL. This streamlines the local development and testing workflow.

```bash
uv run python -m mcp_agent_mail.cli share preview ./my-bundle \
  --port 8080 \
  --open-browser
```

--------------------------------

### Install Guards with Pre-push

Source: https://github.com/dicklesworthstone/mcp_agent_mail/blob/main/README.md

Command to install both pre-commit and pre-push guards for a project. The --prepush flag enables the pre-push guard.

```bash
mcp-agent-mail guard install <project_key> <repo_path> --prepush
```

--------------------------------

### Multi-Project Selection Syntax

Source: https://github.com/dicklesworthstone/mcp_agent_mail/blob/main/README.md

Demonstrates the flexible syntax for selecting projects for export, supporting individual projects, ranges, and combinations.

```bash
Available Projects:
#  Slug                Path
1  backend-abc123      /abs/path/backend
2  frontend-xyz789     /abs/path/frontend
3  infra-def456        /abs/path/infra
4  scripts-ghi789      /abs/path/scripts

Select projects to export (e.g., 'all', '1,3,5', or '1-3'):
```

--------------------------------

### Search FTS Messages Example

Source: https://github.com/dicklesworthstone/mcp_agent_mail/blob/main/docs/planning/project_idea_and_guide.md

An example SQL query to search the fts_messages table using a MATCH clause and joining with the messages table.

```SQL
Search: SELECT m.id FROM fts_messages WHERE fts_messages MATCH ? LIMIT ? and join to messages.
```

--------------------------------

### Scaffold Project Discovery YAML

Source: https://github.com/dicklesworthstone/mcp_agent_mail/blob/main/AGENTS.md

Initializes a discovery YAML file for a project. Specify the product UID when creating this file.

```bash
mcp-agent-mail projects discovery-init . --product <product_uid>
```

--------------------------------

### Serve a bundle locally for preview

Source: https://github.com/dicklesworthstone/mcp_agent_mail/blob/main/README.md

Serves the static files of a bundle on localhost, typically on port 9000, allowing for local previewing in a web browser. Ensure the bundle has been exported first.

```bash
uv run python -m mcp_agent_mail.cli share preview ./my-bundle
```

--------------------------------

### Install Pre-Commit Guard

Source: https://github.com/dicklesworthstone/mcp_agent_mail/blob/main/SKILL.md

Installs a pre-commit guard to prevent commits that conflict with exclusive file reservations. Ensure the AGENT_NAME environment variable is set.

```python
install_precommit_guard(
  project_key="/abs/path/to/project",
  code_repo_path="/abs/path/to/project"
)
```

--------------------------------

### Manage Tutorial UI Feedback

Source: https://github.com/dicklesworthstone/mcp_agent_mail/blob/main/src/mcp_agent_mail/templates/base.html

Methods for tracking completed tutorial actions and displaying toast notifications to the user.

```javascript
markActionComplete(action) { if (!this.completedActions.includes(action)) { this.completedActions.push(action); this.saveProgress(); // Show micro-feedback if (this.isActive) { this.showMicroFeedback(action); } } }, showMicroFeedback(action) { // Small toast or sparkle effect const messages = { 'used_command_palette': '✨ Nice! You used the command palette!', 'viewed_shortcuts': '⌨️ Great! You checked the shortcuts!', 'clicked_inbox': '📬 You found the inbox!', 'searched_messages': '🔍 You tried searching!' }; if (messages[action]) { window.showToast(messages[action], 'success', 2000); } }
```

--------------------------------

### Install Pre-commit Guard

Source: https://github.com/dicklesworthstone/mcp_agent_mail/blob/main/docs/planning/PLAN_TO_NON_DISRUPTIVELY_INTEGRATE_WITH_THE_GIT_WORKTREE_APPROACH.md

Install the pre-commit guard for agent mail using the mcp-agent-mail command. Specify the project slug or human key and the current directory.

```bash
mcp-agent-mail guard install <project-slug-or-human-key> .
```

--------------------------------

### Agent Mail Guard Installation Path

Source: https://github.com/dicklesworthstone/mcp_agent_mail/blob/main/AGENTS.md

The Agent Mail guard is installed as a Python script within the hooks.d directory, ensuring it's executed by the chain-runner.

```shell
hooks.d/pre-commit/50-agent-mail.py
hooks.d/pre-push/50-agent-mail.py
```

--------------------------------

### Initialize and Run a FastMCP Server

Source: https://github.com/dicklesworthstone/mcp_agent_mail/blob/main/third_party_docs/fastmcp_distilled_docs.md

Standard pattern for defining and executing a FastMCP server instance.

```python
# my_server.py
from fastmcp import FastMCP

mcp = FastMCP(name="MyServer")

# ... tool, resource, and prompt definitions ...

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

--------------------------------

### Search Messages Example

Source: https://github.com/dicklesworthstone/mcp_agent_mail/blob/main/SKILL.md

An example of using the search_messages function with a specific FTS5 query to find messages related to the 'auth module' and 'error' but excluding 'legacy'.

```python
search_messages(project_key, '"auth module" AND error NOT legacy')
```

--------------------------------

### Install MCP Agent Mail with Custom Port

Source: https://github.com/dicklesworthstone/mcp_agent_mail/blob/main/README.md

Use this command to install the MCP Agent Mail server and specify a custom port. The default port is 8765.

```bash
curl -fsSL "https://raw.githubusercontent.com/Dicklesworthstone/mcp_agent_mail/main/scripts/install.sh?$(date +%s)" | bash -s -- --port 9000 --yes
```

--------------------------------

### Compose FastMCP Servers with Mounting

Source: https://github.com/dicklesworthstone/mcp_agent_mail/blob/main/third_party_docs/PYTHON_FASTMCP_BEST_PRACTICES.md

Demonstrates server composition by mounting a specialized admin server onto a main FastMCP server with a specific prefix. This allows for modularity and separation of concerns.

```python
# Main server
main_mcp = FastMCP(name="MainServer")

# Create a sub-server for admin tools
admin_mcp = FastMCP(name="AdminTools")
# Add bearer token auth provider only to this server
# mcp.auth = BearerAuthProvider(...)

@admin_mcp.tool
def sensitive_operation(): ...

# Mount the admin server with a prefix and its own auth
main_mcp.mount(admin_mcp, prefix="admin")
```

--------------------------------

### Create a Configuration-Based Proxy

Source: https://github.com/dicklesworthstone/mcp_agent_mail/blob/main/third_party_docs/fastmcp_distilled_docs.md

Initializes a composite proxy server using an MCPConfig dictionary to mount multiple servers.

```python
config = {
    "mcpServers": {
        "weather": {
            "url": "https://weather-api.com/mcp",
            "transport": "http"
        },
        "calendar": {
            "command": "python",
            "args": ["./calendar_server.py"]
        }
    }
}

# This creates a single proxy server that mounts both servers from the config
# with 'weather' and 'calendar' as prefixes.
composite_proxy = FastMCP.as_proxy(config, name="Composite Proxy")
```

--------------------------------

### Install Agent Mail Guards

Source: https://github.com/dicklesworthstone/mcp_agent_mail/blob/main/AGENTS.md

Install agent mail guards for pre-push hooks to ensure compliance with file reservation policies. Guards can be bypassed with --no-verify.

```shell
mcp-agent-mail guard install <project_key> . --prepush
git commit --no-verify
```

--------------------------------

### Get Priority Recommendations with Reasoning

Source: https://github.com/dicklesworthstone/mcp_agent_mail/blob/main/README.md

Use this command to get ranked tasks, impact scores, and confidence levels for agent task selection. It returns JSON output.

```bash
# 1. Get priority recommendations with reasoning
bv --robot-priority
# Returns JSON with ranked tasks, impact scores, and confidence levels
```

--------------------------------

### Link Repository to Product

Source: https://github.com/dicklesworthstone/mcp_agent_mail/blob/main/AGENTS.md

Associates a local repository or worktree with a specified product. Can use a slug or a path.

```bash
mcp-agent-mail products link MyProduct .
```

--------------------------------

### UBS Output Format Example

Source: https://github.com/dicklesworthstone/mcp_agent_mail/blob/main/AGENTS.md

This is an example of the output format from the UBS tool. It includes the category of the issue, the location (file:line:col), a description of the issue, and a suggested fix.

```text
⚠️  Category (N errors)
    file.ts:42:5 – Issue description
    💡 Suggested fix
Exit code: 1
```

--------------------------------

### Client Bootstrap Steps

Source: https://github.com/dicklesworthstone/mcp_agent_mail/blob/main/README.md

Defines the sequence of operations for bootstrapping an MCP client, including resource fetching, tool mounting, and optional metric/recent action retrieval.

```json
{
  "steps": [
    "resources/read -> resource://tooling/directory?format=json",
    "select active cluster (e.g. messaging)",
    "mount tools listed in cluster.tools plus macros if model size <= S",
    "optional: resources/read -> resource://tooling/metrics?format=json for dashboard display",
    "optional: resources/read -> resource://tooling/recent/60?agent=<name>&project=<slug> for UI hints"
  ]
}
```