docs: add MCP client configs and binary documentation (#134, #137)

Author: mihaelamj

CHANGELOG.md

@@ -1,3 +1,22 @@
+## 0.9.1 (2026-01-25)
+
+### Added
+- **MCP client configuration docs** - Added setup guides for multiple AI tools (#134, #137)
+  - OpenAI Codex (CLI and ~/.codex/config.toml)
+  - Cursor (.cursor/mcp.json)
+  - VS Code with GitHub Copilot (.vscode/mcp.json)
+  - Zed (settings.json)
+  - Windsurf (~/.codeium/windsurf/mcp_config.json)
+  - opencode (opencode.jsonc)
+- **Binary documentation** - Full docs for additional executables (#137)
+  - cupertino-tui: Terminal UI with 5 views documented
+  - mock-ai-agent: MCP testing tool with arguments documented
+  - cupertino-rel: Release tool with 6 subcommands and all options
+  - 48 new documentation files in docs/binaries/
+- **mock-ai-agent --version** - Added version flag support (#137)
+
+---
+
 ## 0.9.0 (2025-12-31)
 
 ### Changed

Packages/Sources/MockAIAgent/main.swift

@@ -19,12 +19,18 @@ struct MockAIAgent {
         setbuf(stdout, nil)
         setbuf(stderr, nil)
 
+        // Handle --version flag
+        let args = CommandLine.arguments
+        if args.contains("--version") || args.contains("-v") {
+            print(Shared.Constants.App.version)
+            return
+        }
+
         print("🤖 Mock AI Agent Starting...")
         print("=".repeating(80))
         print()
 
         // Parse command line arguments
-        let args = CommandLine.arguments
         var serverCommand: [String]?
 
         if args.count > 1 {

Packages/Sources/Shared/Constants.swift

@@ -156,7 +156,7 @@ extension Shared {
             public static let userAgent = "CupertinoCrawler/1.0"
 
             /// Current version
-            public static let version = "0.9.0"
+            public static let version = "0.9.1"
 
             /// Database version - separate from CLI version, only bump when schema/content changes
             public static let databaseVersion = "0.8.2"

README.md

@@ -181,6 +181,103 @@ claude mcp add cupertino --scope user -- $(which cupertino)
 
 This registers Cupertino globally for all your projects. Claude Code will automatically have access to Apple documentation search.
 
+### Use with OpenAI Codex
+
+If you're using [OpenAI Codex](https://github.com/openai/codex), add Cupertino with:
+
+```bash
+codex mcp add cupertino -- $(which cupertino) serve
+```
+
+Or add directly to `~/.codex/config.toml`:
+
+```toml
+[mcp_servers.cupertino]
+command = "/opt/homebrew/bin/cupertino"  # Homebrew on Apple Silicon
+# command = "/usr/local/bin/cupertino"   # Intel Mac or manual install
+args = ["serve"]
+```
+
+> **Tip:** Run `which cupertino` to find your installation path.
+
+### Use with Cursor
+
+Add to `.cursor/mcp.json` in your project (or `~/.cursor/mcp.json` for global access):
+
+```json
+{
+  "mcpServers": {
+    "cupertino": {
+      "command": "/opt/homebrew/bin/cupertino",
+      "args": ["serve"]
+    }
+  }
+}
+```
+
+### Use with VS Code (GitHub Copilot)
+
+Add to `.vscode/mcp.json` in your workspace:
+
+```json
+{
+  "servers": {
+    "cupertino": {
+      "type": "stdio",
+      "command": "/opt/homebrew/bin/cupertino",
+      "args": ["serve"]
+    }
+  }
+}
+```
+
+### Use with Zed
+
+Add to your Zed `settings.json`:
+
+```json
+{
+  "context_servers": {
+    "cupertino": {
+      "command": "/opt/homebrew/bin/cupertino",
+      "args": ["serve"]
+    }
+  }
+}
+```
+
+### Use with Windsurf
+
+Add to `~/.codeium/windsurf/mcp_config.json`:
+
+```json
+{
+  "mcpServers": {
+    "cupertino": {
+      "command": "/opt/homebrew/bin/cupertino",
+      "args": ["serve"]
+    }
+  }
+}
+```
+
+### Use with opencode
+
+Add to `opencode.jsonc`:
+
+```json
+{
+  "mcp": {
+    "cupertino": {
+      "type": "local",
+      "command": ["/opt/homebrew/bin/cupertino", "serve"]
+    }
+  }
+}
+```
+
+> **Note:** All examples use `/opt/homebrew/bin/cupertino` (Homebrew on Apple Silicon). Use `/usr/local/bin/cupertino` for Intel Macs or manual installs. Run `which cupertino` to find your path.
+
 ### What You Get
 
 Once configured, Claude Desktop can search your local documentation:
@@ -535,7 +632,7 @@ For development setup, see [DEVELOPMENT.md](DEVELOPMENT.md).
 
 ## Project Status
 
-**Version:** 0.9.0
+**Version:** 0.9.1
 **Status:** 🚧 Active Development
 
 - ✅ All core functionality working

docs/DEPLOYMENT.md

@@ -1,6 +1,6 @@
 # Cupertino Deployment Guide
 
-**Version:** 0.9.0
+**Version:** 0.9.1
 **Last Updated:** 2025-12-12
 
 This guide covers the complete release process for Cupertino.

docs/binaries/README.md

@@ -0,0 +1,31 @@
+# Cupertino Binaries
+
+Executable binaries included in the Cupertino package.
+
+## Binaries
+
+| Binary | Description |
+|--------|-------------|
+| [cupertino-tui](cupertino-tui/) | Terminal UI for browsing packages, archives, and settings |
+| [mock-ai-agent](mock-ai-agent/) | MCP testing tool for debugging server communication |
+| [cupertino-rel](cupertino-rel/) | Release automation tool (maintainers only) |
+
+## Installation
+
+All binaries are built when you run:
+
+```bash
+cd Packages
+swift build -c release
+```
+
+The binaries are located in `.build/release/`:
+- `.build/release/cupertino`
+- `.build/release/cupertino-tui`
+- `.build/release/mock-ai-agent`
+- `.build/release/cupertino-rel`
+
+## See Also
+
+- [Commands](../commands/) - Main CLI commands (`cupertino`)
+- [Tools](../tools/) - MCP tools provided by the server

docs/binaries/cupertino-rel/README.md

@@ -0,0 +1,89 @@
+# cupertino-rel
+
+Release automation tool for Cupertino maintainers.
+
+## Synopsis
+
+```bash
+cupertino-rel [options] [subcommand]
+```
+
+## Options
+
+| Option | Description |
+|--------|-------------|
+| [--version](option (--)/version.md) | Show version information |
+| -h, --help | Show help information |
+
+## Description
+
+Automates the complete Cupertino release workflow:
+
+1. Update version in `Constants.swift`, `README.md`, `CHANGELOG.md`
+2. Commit version bump
+3. Create and push git tag
+4. Wait for GitHub Actions to build
+5. Upload databases via `cupertino release`
+6. Update Homebrew formula
+
+## Requirements
+
+- `GITHUB_TOKEN` environment variable with `repo` scope
+
+## Subcommands
+
+| Subcommand | Description |
+|------------|-------------|
+| `full` | Run the complete release workflow (default) |
+| `bump` | Bump version in all required files |
+| `tag` | Commit changes and create git tag |
+| `databases` | Package and upload databases to GitHub Releases |
+| `homebrew` | Update Homebrew formula with new version |
+| `docs-update` | Update documentation databases and bump minor version |
+
+## Usage
+
+### Full Release
+
+```bash
+# Run complete release workflow (major/minor/patch)
+cupertino-rel full --bump-type patch
+cupertino-rel full --bump-type minor
+cupertino-rel full --bump-type major
+```
+
+### Individual Steps
+
+```bash
+# Bump version only
+cupertino-rel bump --type patch
+
+# Create and push tag
+cupertino-rel tag
+
+# Upload databases
+cupertino-rel databases
+
+# Update Homebrew formula
+cupertino-rel homebrew
+```
+
+### Documentation Update
+
+```bash
+# Update docs databases and bump minor version
+cupertino-rel docs-update
+```
+
+## Version Bump Locations
+
+The `bump` command updates version in:
+
+- `Sources/Shared/Constants.swift` - App version constant
+- `README.md` - Version badge and references
+- `CHANGELOG.md` - New version section
+
+## See Also
+
+- [DEVELOPMENT.md](../../../DEVELOPMENT.md) - Development workflow
+- [DEPLOYMENT.md](../DEPLOYMENT.md) - Deployment and CI/CD

docs/binaries/cupertino-rel/option (--)/version.md

@@ -0,0 +1,20 @@
+# --version
+
+Show version information.
+
+## Synopsis
+
+```bash
+cupertino-rel --version
+```
+
+## Description
+
+Prints the Cupertino version and exits.
+
+## Example
+
+```bash
+$ cupertino-rel --version
+0.9.0
+```

docs/binaries/cupertino-rel/subcommand/bump/README.md

@@ -0,0 +1,39 @@
+# cupertino-rel bump
+
+Bump version in all required files.
+
+## Synopsis
+
+```bash
+cupertino-rel bump <version-or-type> [options]
+```
+
+## Description
+
+Updates the version number in:
+- `Sources/Shared/Constants.swift`
+- `README.md`
+- `CHANGELOG.md`
+
+## Arguments
+
+| Argument | Description |
+|----------|-------------|
+| [version-or-type](argument (<>)/version-or-type.md) | New version (e.g., 0.5.0) or bump type (major, minor, patch) |
+
+## Options
+
+| Option | Description |
+|--------|-------------|
+| [--dry-run](option (--)/dry-run.md) | Preview changes without modifying files |
+| [--repo-root](option (--)/repo-root.md) | Path to repository root |
+
+## Examples
+
+```bash
+cupertino-rel bump patch        # 0.9.0 → 0.9.1
+cupertino-rel bump minor        # 0.9.0 → 0.10.0
+cupertino-rel bump major        # 0.9.0 → 1.0.0
+cupertino-rel bump 1.0.0        # Set exact version
+cupertino-rel bump patch --dry-run  # Preview only
+```

docs/binaries/cupertino-rel/subcommand/bump/argument (<>)/version-or-type.md

@@ -0,0 +1,29 @@
+# <version-or-type>
+
+Version or bump type argument.
+
+## Synopsis
+
+```bash
+cupertino-rel bump <version-or-type>
+```
+
+## Description
+
+Specify either an exact version number or a bump type.
+
+## Values
+
+| Value | Description | Example |
+|-------|-------------|---------|
+| `major` | Bump major version | 0.9.0 → 1.0.0 |
+| `minor` | Bump minor version | 0.9.0 → 0.10.0 |
+| `patch` | Bump patch version | 0.9.0 → 0.9.1 |
+| `X.Y.Z` | Set exact version | 0.9.0 → 1.0.0 |
+
+## Examples
+
+```bash
+cupertino-rel bump patch    # Increment patch
+cupertino-rel bump 2.0.0    # Set to 2.0.0
+```