# 2. Information Architecture (IA)

## 2.1. CLI Command Structure & Design

- **Main Command:** `fabric-mcp`.
- **Overall Structure:** Flat, with a primary mandatory `--transport <MODE>` flag for server operation, where `<MODE>` is one of `stdio`, `http`, or `sse` (case-insensitive).
- **Key Flags/Options:**
  - `--transport {stdio|http|sse}`: Specifies the MCP transport mode.
  - `--host <hostname>`: For `http`/`sse` transports, specifies host. (Default: e.g., `127.0.0.1`).
  - `--port <port_number>`: For `http`/`sse` transports, specifies port. (Default: e.g., `8000` for HTTP, `8001` for SSE to avoid conflict).
  - `--path <http_path>`: For `http`/`sse` transports, specifies MCP endpoint path. (Default: e.g., `/mcp` for HTTP, `/sse` for SSE).
  - `--log-level {DEBUG|INFO|WARNING|ERROR|CRITICAL}`: Sets logging verbosity. (Default: `INFO`).
  - `--version`: Displays server version.
  - `--help` / `-h`: Displays help message.
- **Flag Naming Convention:** `kebab-case` (e.g., `--log-level`).
- **Help Message Structure (`fabric-mcp --help`):** Generated by `click`. Must include usage line, brief description, and clearly list all options with arguments, choices, descriptions, and default values. Options should be grouped logically (e.g., "Transport Options," "General Options").
- **No-Args/Invalid-Args Behavior:** If `--transport` is not specified, or an invalid mode/option is given, the CLI prints help to stderr and exits with a non-zero status code.
- **Shell Completion:** The CLI design with `--transport <MODE>` supports discoverability via shell completion, a desired DX feature.
- **Startup Connectivity Check:** On startup, `fabric-mcp` will attempt to query a lightweight endpoint (e.g., `/config` or `/version`) of the configured Fabric API to verify connectivity and authentication, providing clear success or actionable error messages in the logs.

## 2.2. MCP Tool Organization & Discoverability

- **Tool Naming Convention:** `fabric_verb_noun` (e.g., `fabric_list_patterns`).
- **Discoverability via `list_tools()`:** This MCP command is the primary mechanism for client developers to discover tools. The response for each tool MUST include:
  - `name`: Exact tool name.
  - `description`: Clear, concise, user-centric explanation.
  - `parameters`: List of parameter objects, each detailing `name` (snake_case), `type`, `required` (boolean), and `description` (purpose, constraints, defaults).
  - `return_value`: Object detailing `type` and `description` of the expected successful response.
- **Consistency:** Enforced for parameter naming and data structures across all tools.
- **Getting Tool Details:** The `list_tools()` response serves as the comprehensive definition. The MCP Inspector is the recommended way for developers to explore these details interactively.

## 2.3. Configuration Information

- **Naming Conventions:** Environment variables in `UPPER_SNAKE_CASE` (e.g., `FABRIC_API_KEY`); CLI flags in `kebab-case`.
- **Discoverability/Documentation:** A dedicated "Configuration" section in `README.md` and comprehensive details in `fabric-mcp --help` for CLI options.
- **Defaults:** Sensible defaults for log level, transport host/port/path MUST be used and clearly documented.
- **Precedence:** For settings configurable by both CLI flag and environment variable (e.g., log level), CLI flags override environment variables.
- **Validation & Error Reporting:** Missing or invalid configurations must result in clear, actionable error messages at startup, guiding the user to the problematic setting.
- **Security of Sensitive Configuration:** Documentation will remind users about secure handling of `FABRIC_API_KEY`.

## 2.4. User-Facing Documentation Structure (Conceptual)

- **Existing Documentation:** Acknowledges the user's existing documentation in their GitHub repository, with `README.md` as the primary entry point.
- **Key Emphasis Points for User Documentation:**
  - **Discoverability:** Easy navigation from the main project page (`README.md`).
  - **Clarity for All Personas:** Sections or guides catering to General Developers, MCP Client Developers, and Server Administrators.
  - **Practical Examples:** Crucial for CLI commands and MCP tool usage.
  - **Comprehensive Configuration Details:** Covering all environment variables and CLI options.
- **In-Context Documentation:** The CLI's `--help` output and the MCP `list_tools()` response are vital sources of in-context documentation.
