[feature] Add declarative optional MCP framework and zhtw-mcp optional integration

[tryweb]

Summary

Add a declarative optional MCP framework to ai-engkit so non-core MCP tools can be enabled safely without relying on ad-hoc in-container installs or manual opencode mcp add drift.

Problem / use case

Today ai-engkit's built-in MCP stack is durable because:

• binaries are installed at image build time,
• entrypoint.d/02-init-config.sh regenerates ~/.config/opencode/opencode.json on startup,
• selected tool state is stored on volumes.

That model does not yet exist for optional MCPs. In Docker, a manually installed MCP can disappear after recreate/rebuild, while a manually added OpenCode MCP entry can be overwritten when opencode.json is regenerated.

zhtw-mcp is a good motivating case:

• useful only for some users,
• single-binary Rust tool,
• not auto-registered to OpenCode by upstream install scripts.

Proposed solution

Implement an optional MCP registry consumed by the entrypoint when generating OpenCode config.

High-level design:

• add /etc/opencode/optional-mcp.json for image defaults
• add ~/.config/opencode/optional-mcp.json for persistent user overrides
• merge both registries during startup
• append only enabled MCP entries whose commands resolve successfully
• create any declared required paths before registration
• keep opencode.json entrypoint-owned instead of user-mutated

Initial design draft:

• docs/knowledge/architecture/optional-mcp-architecture.md

Alternatives considered

1. Manual opencode mcp add inside the container

   • fragile because opencode.json is regenerated on startup
   • easy to lose during rebuild/recreate

2. Volume-only optional MCP installs

   • workable, but requires extra persistent binary path management and more recovery logic

3. Bake every candidate MCP into the base image and enable all by default

   • simplest operationally, but wrong for niche tools and image bloat

Scope and impact

• install flow
• upgrade flow
• Docker image
• runtime tooling
• authentication
• documentation
• testing
• CI/CD
• other

Other:

• OpenCode config generation
• optional persistence paths for MCP-local caches/config

Additional context

Recommended phased rollout:

1. Add the generic optional MCP framework first.
2. Add tests for disabled, enabled, and missing-binary cases.
3. Integrate zhtw-mcp as the first optional MCP.

Recommended initial zhtw-mcp treatment:

• install strategy: image-baked binary
• default: disabled
• enabled via env and/or persistent user override file

Language

Traditional Chinese acceptable.

Checklist

• I searched existing issues first
• This is not a security report
• I described the problem and expected benefit