Merge pull request #47 from LittleCoinCoin/dev

[v0.8.1.dev1] OpenCode MCP host, adding-mcp-hosts skill, and dev docs refresh

Author: LittleCoinCoin

.claude/skills/adding-mcp-hosts/SKILL.md

@@ -0,0 +1,202 @@
+---
+name: adding-mcp-hosts
+description: |
+  Adds support for a new MCP host platform to the Hatch CLI multi-host
+  configuration system. Use when asked to add, integrate, or extend MCP host
+  support for a new IDE, editor, or AI coding tool (e.g., Windsurf, Zed,
+  Copilot). Follows a 5-step workflow: discover host requirements via web
+  research or user questionnaire, add enum and field set declarations, create
+  adapter and strategy implementations, wire integration points across 4
+  registration files, and register test fixtures that auto-generate 20+ test
+  cases without writing test code.
+---
+
+## Workflow Checklist
+
+```
+- [ ] Step 1: Discover host requirements
+- [ ] Step 2: Add enum and field set
+- [ ] Step 3: Create adapter and strategy
+- [ ] Step 4: Wire integration points
+- [ ] Step 5: Register test fixtures
+```
+
+---
+
+## Step 1: Discover Host Requirements
+
+Read [references/discovery-guide.md](references/discovery-guide.md) for the full discovery workflow.
+
+Use web search, Context7, and codebase retrieval to find the target host's MCP
+configuration: config file path per platform, format (JSON/JSONC/TOML), top-level key,
+every supported field name and type, and any field name differences from the universal
+set (`command`, `args`, `env`, `url`, `headers`).
+
+If research leaves blockers unresolved, present the structured questionnaire from the
+discovery guide to the user.
+
+Write `__reports__/<host-name>/00-parameter_analysis_v0.md` (field-level discovery) and
+`__reports__/<host-name>/01-architecture_analysis_v0.md` (integration analysis and NO-GO
+assessment). Also produce the Host Spec YAML block — it feeds all subsequent steps.
+
+---
+
+## Step 2: Add Enum and Field Set
+
+Add `MCPHostType` enum value in `hatch/mcp_host_config/models.py`:
+
+```python
+class MCPHostType(str, Enum):
+    # ... existing members ...
+    YOUR_HOST = "your-host"  # lowercase-hyphenated, matching Host Spec slug
+```
+
+Add field set constant in `hatch/mcp_host_config/fields.py`:
+
+```python
+YOUR_HOST_FIELDS: FrozenSet[str] = UNIVERSAL_FIELDS | frozenset(
+    {
+        # host-specific fields from Host Spec
+    }
+)
+```
+
+Include `"type"` (via `CLAUDE_FIELDS` base) only if the host uses a transport type
+discriminator. If the host uses different field names for universal concepts, add a
+mappings dict (see `CODEX_FIELD_MAPPINGS` pattern in `fields.py`).
+
+If the host introduces fields not in `MCPServerConfig`, add them as `Optional` fields
+with `Field(None, description="...")` under a new section comment block in `models.py`.
+
+Verify:
+
+```bash
+python -c "from hatch.mcp_host_config.models import MCPHostType; print(MCPHostType.YOUR_HOST)"
+python -c "from hatch.mcp_host_config.fields import YOUR_HOST_FIELDS; print(YOUR_HOST_FIELDS)"
+```
+
+---
+
+## Step 3: Create Adapter and Strategy
+
+Read [references/adapter-contract.md](references/adapter-contract.md) for the `BaseAdapter`
+interface, the `validate_filtered()` pipeline, and field mapping details.
+
+Read [references/strategy-contract.md](references/strategy-contract.md) for the
+`MCPHostStrategy` interface, `@register_host_strategy` decorator, platform path resolution,
+and config serialization.
+
+### Adapter
+
+Create `hatch/mcp_host_config/adapters/your_host.py`. Implement `BaseAdapter` with:
+
+- `host_name` property returning the slug
+- `get_supported_fields()` returning the field set from Step 2
+- `validate_filtered(filtered)` enforcing host-specific transport rules
+- `serialize(config)` calling `filter_fields()` then `validate_filtered()` then returning
+  the dict (apply field mappings if needed)
+
+**Variant shortcut:** If the new host is functionally identical to an existing host,
+register it as a variant instead of creating a new file. See
+`ClaudeAdapter(variant=...)` in `hatch/mcp_host_config/adapters/claude.py`.
+
+### Strategy
+
+Add a strategy class in `hatch/mcp_host_config/strategies.py` decorated with
+`@register_host_strategy(MCPHostType.YOUR_HOST)`. Decide the family:
+
+- `ClaudeHostStrategy` -- JSON format with `mcpServers` key
+- `CursorBasedHostStrategy` -- `.cursor/mcp.json`-like layout
+- `MCPHostStrategy` (direct) -- standalone hosts with unique formats
+
+Implement `get_config_path()`, `get_config_key()`, `validate_server_config()`,
+`read_config()`, and `write_config()`.
+
+Verify:
+
+```bash
+python -c "from hatch.mcp_host_config.adapters.your_host import YourHostAdapter; print(YourHostAdapter().host_name)"
+```
+
+---
+
+## Step 4: Wire Integration Points
+
+Four files need one-liner additions.
+
+**`hatch/mcp_host_config/adapters/__init__.py`** -- Import and add to `__all__`:
+
+```python
+from hatch.mcp_host_config.adapters.your_host import YourHostAdapter
+# Append "YourHostAdapter" to __all__
+```
+
+**`hatch/mcp_host_config/adapters/registry.py`** -- Import adapter, add
+`self.register(YourHostAdapter())` inside `_register_defaults()`.
+
+**`hatch/mcp_host_config/backup.py`** -- Add `"your-host"` to the `supported_hosts` set
+in `BackupInfo.validate_hostname()`. Also update the `supported_hosts` set in
+`EnvironmentPackageEntry.validate_host_names()` in `models.py`.
+
+**`hatch/mcp_host_config/reporting.py`** -- Add `MCPHostType.YOUR_HOST: "your-host"` to
+the `mapping` dict in `_get_adapter_host_name()`.
+
+Verify:
+
+```bash
+python -c "
+from hatch.mcp_host_config.adapters.registry import AdapterRegistry
+r = AdapterRegistry()
+print('your-host' in r.get_supported_hosts())
+"
+```
+
+---
+
+## Step 5: Register Test Fixtures
+
+Read [references/testing-fixtures.md](references/testing-fixtures.md) for fixture schemas,
+auto-generated test case details, and pytest commands.
+
+Add canonical config entry in `tests/test_data/mcp_adapters/canonical_configs.json`:
+
+```json
+"your-host": {
+  "command": "python",
+  "args": ["-m", "mcp_server"],
+  "env": {"API_KEY": "test_key"},
+  "url": null,
+  "headers": null
+}
+```
+
+Include all host-specific fields with representative values. Use `null` for unused
+transport fields.
+
+Add host registry entries in `tests/test_data/mcp_adapters/host_registry.py`:
+
+1. Import the new field set and adapter.
+2. Add `FIELD_SETS` entry: `"your-host": YOUR_HOST_FIELDS`.
+3. Add `adapter_map` entry in `HostSpec.get_adapter()`.
+4. Add reverse mappings if the host has field name mappings.
+5. Add the new field set to `all_possible_fields` in `generate_unsupported_field_test_cases()`.
+
+Verify:
+
+```bash
+python -m pytest tests/integration/mcp/ tests/unit/mcp/ tests/regression/mcp/ -v
+```
+
+All existing tests must pass. The new host auto-generates test cases for cross-host sync
+(N x N matrix), field filtering, transport validation, and property checks.
+
+---
+
+## Cross-References
+
+| Reference | Covers | Read when |
+|---|---|---|
+| [references/discovery-guide.md](references/discovery-guide.md) | Host research, questionnaire, Host Spec YAML | Step 1 (always) |
+| [references/adapter-contract.md](references/adapter-contract.md) | BaseAdapter interface, field sets, registry wiring | Step 3 (always) |
+| [references/strategy-contract.md](references/strategy-contract.md) | MCPHostStrategy interface, families, platform paths | Step 3 (always) |
+| [references/testing-fixtures.md](references/testing-fixtures.md) | Fixture schema, auto-generated tests, pytest commands | Step 5 (always) |

.claude/skills/adding-mcp-hosts/references/adapter-contract.md

@@ -0,0 +1,157 @@
+# Adapter Contract Reference
+
+Interface contract for implementing a new MCP host adapter in the Hatch CLI.
+
+## 1. MCPHostType Enum
+
+File: `hatch/mcp_host_config/models.py`. Convention: `UPPER_SNAKE = "kebab-case"`.
+
+```python
+class MCPHostType(str, Enum):
+    # ... existing members ...
+    NEW_HOST = "new-host"
+```
+
+The enum value string is the canonical host identifier used everywhere.
+
+## 2. Field Set Declaration
+
+File: `hatch/mcp_host_config/fields.py`. Define a `<HOST>_FIELDS` frozenset.
+
+```python
+# Without 'type' support — build from UNIVERSAL_FIELDS
+NEW_HOST_FIELDS: FrozenSet[str] = UNIVERSAL_FIELDS | frozenset({"host_specific_field"})
+
+# With 'type' support — build from CLAUDE_FIELDS (which is UNIVERSAL_FIELDS | {"type"})
+NEW_HOST_FIELDS: FrozenSet[str] = CLAUDE_FIELDS | frozenset({"host_specific_field"})
+```
+
+If the host supports the `type` discriminator, also add its kebab-case name to `TYPE_SUPPORTING_HOSTS`. Hosts without `type` support (Gemini, Kiro, Codex) omit this.
+
+## 3. MCPServerConfig Fields
+
+File: `hatch/mcp_host_config/models.py`. Add new fields to `MCPServerConfig` only when the host introduces fields not already in the model. Every field: `Optional`, default `None`.
+
+```python
+disabled: Optional[bool] = Field(None, description="Whether server is disabled")
+```
+
+If the host reuses existing fields only (e.g., LMStudio reuses `CLAUDE_FIELDS`), skip this step. The model uses `extra="allow"` but explicit declarations are preferred.
+
+## 4. Adapter Class
+
+File: `hatch/mcp_host_config/adapters/<host>.py`. Extend `BaseAdapter`.
+
+```python
+from typing import Any, Dict, FrozenSet
+from hatch.mcp_host_config.adapters.base import AdapterValidationError, BaseAdapter
+from hatch.mcp_host_config.fields import NEW_HOST_FIELDS
+from hatch.mcp_host_config.models import MCPServerConfig
+
+class NewHostAdapter(BaseAdapter):
+
+    @property
+    def host_name(self) -> str:
+        return "new-host"
+
+    def get_supported_fields(self) -> FrozenSet[str]:
+        return NEW_HOST_FIELDS
+
+    def validate(self, config: MCPServerConfig) -> None:
+        pass  # DEPRECATED — kept for ABC compliance until v0.9.0
+
+    def validate_filtered(self, filtered: Dict[str, Any]) -> None:
+        has_command = "command" in filtered
+        has_url = "url" in filtered
+        if not has_command and not has_url:
+            raise AdapterValidationError(
+                "Either 'command' (local) or 'url' (remote) must be specified",
+                host_name=self.host_name,
+            )
+        if has_command and has_url:
+            raise AdapterValidationError(
+                "Cannot specify both 'command' and 'url' - choose one transport",
+                host_name=self.host_name,
+            )
+
+    def serialize(self, config: MCPServerConfig) -> Dict[str, Any]:
+        filtered = self.filter_fields(config)
+        self.validate_filtered(filtered)
+        return filtered  # add apply_transformations() call if field mappings exist
+```
+
+**validate_filtered() rules:** Transport mutual exclusion (`command` XOR `url` for most hosts; Gemini enforces exactly-one-of-three including `httpUrl`). If host supports `type`, verify consistency (`type='stdio'` requires `command`, etc.).
+
+**serialize() pipeline:** Always `filter_fields` -> `validate_filtered` -> optionally `apply_transformations` -> return.
+
+## 5. Field Mappings
+
+File: `hatch/mcp_host_config/fields.py`. Define only when the host uses different field names. Pattern: `{"universal_name": "host_name"}`. Canonical example:
+
+```python
+CODEX_FIELD_MAPPINGS: dict[str, str] = {
+    "args": "arguments",
+    "headers": "http_headers",
+    "includeTools": "enabled_tools",
+    "excludeTools": "disabled_tools",
+}
+```
+
+Reference in `apply_transformations()`:
+
+```python
+def apply_transformations(self, filtered: Dict[str, Any]) -> Dict[str, Any]:
+    result = filtered.copy()
+    for universal_name, host_name in NEW_HOST_FIELD_MAPPINGS.items():
+        if universal_name in result:
+            result[host_name] = result.pop(universal_name)
+    return result
+```
+
+Skip entirely if the host uses standard field names (most do).
+
+## 6. Variant Pattern
+
+Reuse one adapter class with a `variant` parameter when two host identifiers share identical fields and validation. Canonical example:
+
+```python
+class ClaudeAdapter(BaseAdapter):
+    def __init__(self, variant: str = "desktop"):
+        if variant not in ("desktop", "code"):
+            raise ValueError(f"Invalid Claude variant: {variant}")
+        self._variant = variant
+
+    @property
+    def host_name(self) -> str:
+        return f"claude-{self._variant}"
+```
+
+Use when field set, validation, and serialization are identical. If any diverge, create a separate class.
+
+## 7. Wiring and Integration Points
+
+Four files require one-liner additions for every new host.
+
+**`hatch/mcp_host_config/adapters/__init__.py`** -- Add import and `__all__` entry:
+```python
+from hatch.mcp_host_config.adapters.new_host import NewHostAdapter
+# add "NewHostAdapter" to __all__
+```
+
+**`hatch/mcp_host_config/adapters/registry.py`** -- Add to `_register_defaults()`:
+```python
+self.register(NewHostAdapter())  # import at top of file
+```
+
+**`hatch/mcp_host_config/backup.py`** -- Add hostname string to `supported_hosts` set in `BackupInfo.validate_hostname()`:
+```python
+supported_hosts = {
+    # ... existing hosts ...
+    "new-host",
+}
+```
+
+**`hatch/mcp_host_config/reporting.py`** -- Add entry to mapping dict in `_get_adapter_host_name()`:
+```python
+MCPHostType.NEW_HOST: "new-host",
+```