airc-cli 0.1.2 → 0.1.5

package/README.md

@@ -30,6 +30,7 @@ This creates:
 - `~/.airc/config/skills/` - Local skills config storage
 - `~/.airc/config/commands/` - Local commands config storage
 - `~/.airc/config/agents/` - Local commands config storage
+- `~/.airc/config/mcp-config.json` - MCP server configurations
 - `~/.aircrc` - Configuration file for airc cli
 
 ### 2. Add a Source
@@ -104,3 +105,171 @@ airc/
 │   ├── agents/       # Agent definitions
 │   └── scripts/      # Add your own config folder
 ```
+
+## Managing MCPs (Model Context Protocol)
+
+airc now supports managing MCP (Model Context Protocol) server configurations. MCPs allow AI tools to interact with external systems and services through standardized server interfaces.
+
+### MCP Config Structure
+
+MCP configurations are stored in `~/.airc/config/mcp-config.json`:
+
+```json
+{
+  "filesystem": {
+    "type": "stdio",
+    "command": "npx",
+    "args": ["-y", "@modelcontextprotocol/server-filesystem", "/Users"]
+  },
+  "github": {
+    "type": "stdio",
+    "command": "npx",
+    "args": ["-y", "@modelcontextprotocol/server-github"],
+    "env": {
+      "GITHUB_PERSONAL_ACCESS_TOKEN": "your_token_here"
+    }
+  }
+}
+```
+
+**Field Descriptions:**
+- `type`: Protocol type (currently only "stdio" is supported)
+- `command`: The command to run the MCP server (e.g., "npx", "node")
+- `args`: Array of command arguments (optional)
+- `env`: Environment variables for the server (optional)
+
+### Viewing MCPs
+
+List all available MCPs along with your other configs:
+
+```bash
+airc list
+```
+
+**Example output:**
+```
+📋 Your Configs
+
+📦 Commands (2)
+✏️  manual commit
+✏️  manual push
+
+📦 MCP Configs (2)
+✏️  manual filesystem
+       type: stdio
+✏️  manual github
+       type: stdio
+
+Total: 4 configs
+  0 imported, 4 manual
+```
+
+### Installing MCPs to AI Tools
+
+When you run `airc install <tool>`, you'll be prompted to select which MCPs to install:
+
+```bash
+# Install to Claude (project-level)
+cd <project-root>
+airc install claude
+
+# Install globally
+airc install claude --global
+```
+
+**Interactive MCP selection:**
+```
+📦 MCP Configs
+? Select MCPs to install: (Press <space> to select, <a> to toggle all)
+❯◯ filesystem (stdio)
+ ◯ github (stdio)
+```
+
+After selection, MCPs are merged into the tool's config file:
+```
+✅ Successfully installed 2 MCP configs
+   Installed to: .mcp.json
+```
+
+### Handling MCP Conflicts
+
+If an MCP with the same name already exists in the tool's config, use the `--force` flag to overwrite:
+
+```bash
+airc install claude --force
+```
+
+**Without --force:**
+```
+❌ Error: MCP conflicts detected: filesystem, github
+   These MCPs already exist in the config file.
+   Use --force to overwrite existing MCPs.
+```
+
+**With --force:**
+```
+✅ Successfully installed 2 MCP configs (overwrote 2 existing)
+```
+
+### Removing MCPs
+
+Remove an MCP from your local configuration:
+
+```bash
+airc remove <mcp-name> --force
+```
+
+**Example:**
+```bash
+airc remove github --force
+```
+
+**Output:**
+```
+🗑️  Remove Config
+
+MCP Config: github
+Type: stdio
+Source: manual (MCP configuration)
+
+✅ Successfully removed MCP "github"
+   MCP removed from ~/.airc/config/mcp-config.json
+```
+
+### Tool-Specific MCP Support
+
+Different AI tools store MCPs in different locations with different field names:
+
+| Tool | Project Mode Path | Global Mode Path | Field Name |
+|------|------------------|------------------|------------|
+| Claude | `.mcp.json` | `~/.claude.json` | `mcpServers` |
+| Gemini | `.gemini/settings.json` | `~/.gemini/settings.json` | `mcpServers` |
+| Antigravity | N/A (global only) | `~/.gemini/antigravity/mcp_config.json` | `mcpServers` |
+| Cursor | `.cursor/mcp.json` | `~/.cursor/mcp.json` | `mcpServers` |
+| Copilot | `.copilot/mcp-config.json` | `~/.copilot/mcp-config.json` | `mcpServers` |
+| OpenCode | `opencode.json` | `~/.config/opencode/opencode.json` | `mcp` |
+
+**Note:** Antigravity only supports global mode. When installing to Antigravity in project mode, you'll see an informational message:
+
+```
+ℹ️  Note: Antigravity only supports global MCP installation
+   Use --global flag to install MCPs for Antigravity
+```
+
+### Troubleshooting
+
+**MCPs not showing in `airc list`:**
+- Ensure `~/.airc/config/mcp-config.json` exists and contains valid JSON
+- Check file permissions on the mcp-config.json file
+
+**MCP installation fails:**
+- Verify the tool supports MCP format (see table above)
+- For Antigravity, use `--global` flag
+- Check that the target config file has write permissions
+- Use `--force` flag if MCPs already exist and you want to overwrite
+
+**MCPs not working after installation:**
+- Verify the MCP server command is correctly installed (e.g., `npx @modelcontextprotocol/server-filesystem`)
+- Check environment variables are set correctly in the MCP config
+- Restart your AI tool after installing MCPs
+- Consult the specific AI tool's documentation for MCP troubleshooting