moonbridge 0.2.0__tar.gz

moonbridge-0.2.0/.env.example

@@ -0,0 +1,15 @@
+# Moonbridge MCP Server Configuration
+# Copy to .env and modify as needed
+
+# Default timeout for agent execution (30-3600 seconds)
+# MOONBRIDGE_TIMEOUT=600
+
+# Maximum number of parallel agents
+# MOONBRIDGE_MAX_AGENTS=10
+
+# Colon-separated allowlist of working directories
+# Leave unset to allow all directories
+# MOONBRIDGE_ALLOWED_DIRS=/path/to/project:/another/path
+
+# Log level (DEBUG, INFO, WARNING, ERROR)
+# MOONBRIDGE_LOG_LEVEL=WARNING

moonbridge-0.2.0/.github/workflows/publish.yml

@@ -0,0 +1,29 @@
+name: publish
+
+on:
+  release:
+    types: [published]
+
+permissions:
+  contents: write  # needed for creating releases
+  id-token: write
+
+jobs:
+  publish:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-python@v5
+        with:
+          python-version: "3.11"
+      - name: Build
+        run: |
+          python -m pip install --upgrade pip
+          pip install build
+          python -m build
+      - name: Publish
+        uses: pypa/gh-action-pypi-publish@release/v1
+      - name: Create GitHub Release
+        uses: softprops/action-gh-release@v2
+        with:
+          generate_release_notes: true

moonbridge-0.2.0/.github/workflows/release-please.yml

@@ -0,0 +1,22 @@
+name: release-please
+
+on:
+  push:
+    branches:
+      - master
+
+permissions:
+  contents: write
+  pull-requests: write
+
+jobs:
+  release-please:
+    runs-on: ubuntu-latest
+    outputs:
+      release_created: ${{ steps.release.outputs.release_created }}
+      tag_name: ${{ steps.release.outputs.tag_name }}
+    steps:
+      - uses: googleapis/release-please-action@v4
+        id: release
+        with:
+          token: ${{ secrets.GITHUB_TOKEN }}

moonbridge-0.2.0/.github/workflows/test.yml

@@ -0,0 +1,27 @@
+name: tests
+
+on:
+  push:
+  pull_request:
+
+jobs:
+  test:
+    runs-on: ubuntu-latest
+    strategy:
+      matrix:
+        python-version: ["3.11", "3.12", "3.13"]
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-python@v5
+        with:
+          python-version: ${{ matrix.python-version }}
+      - name: Install deps
+        run: |
+          python -m pip install --upgrade pip
+          pip install -e ".[dev]"
+      - name: Ruff
+        run: ruff check src/
+      - name: Mypy
+        run: mypy src/
+      - name: Pytest
+        run: pytest -v

moonbridge-0.2.0/.gitignore

@@ -0,0 +1,10 @@
+__pycache__/
+*.pyc
+.venv/
+dist/
+*.egg-info/
+.mypy_cache/
+.pytest_cache/
+.ruff_cache/
+
+thinktank*

moonbridge-0.2.0/.release-please-manifest.json

@@ -0,0 +1,3 @@
+{
+  ".": "0.2.0"
+}

moonbridge-0.2.0/CHANGELOG.md

@@ -0,0 +1,32 @@
+# Changelog
+
+All notable changes to this project will be documented in this file.
+
+The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
+and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
+
+## [0.2.0](https://github.com/misty-step/moonbridge/compare/moonbridge-v0.1.0...moonbridge-v0.2.0) (2026-01-28)
+
+
+### Features
+
+* initial moonbridge MCP server ([3debd32](https://github.com/misty-step/moonbridge/commit/3debd325a1619bbbfe980a258c134665bce36e6d))
+
+## [0.1.0] - 2026-01-28
+
+### Added
+- Initial release
+- `spawn_agent` tool for single Kimi agent execution
+- `spawn_agents_parallel` tool for concurrent agent swarms (up to 10)
+- `check_status` tool for CLI verification
+- Configurable timeouts (30-3600 seconds)
+- Working directory allowlist via `MOONBRIDGE_ALLOWED_DIRS`
+- Structured JSON responses with status, output, stderr, and timing
+- Authentication error detection with actionable messages
+- Process group management for clean termination
+- Extended reasoning mode via `thinking` parameter
+
+### Security
+- Sanitized environment variables passed to subprocesses
+- Symlink-aware path validation to prevent directory traversal
+- Prompt length validation to prevent resource exhaustion

moonbridge-0.2.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 Phaedrus
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

moonbridge-0.2.0/PKG-INFO

@@ -0,0 +1,194 @@
+Metadata-Version: 2.4
+Name: moonbridge
+Version: 0.2.0
+Summary: MCP server for spawning Kimi K2.5 agents
+Project-URL: Homepage, https://github.com/misty-step/moonbridge
+Project-URL: Repository, https://github.com/misty-step/moonbridge
+Project-URL: Issues, https://github.com/misty-step/moonbridge/issues
+Author-email: Phaedrus <hello@mistystep.io>
+License-Expression: MIT
+License-File: LICENSE
+Keywords: agent,ai,claude,kimi,mcp
+Classifier: Development Status :: 4 - Beta
+Classifier: Environment :: Console
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Requires-Python: >=3.11
+Requires-Dist: mcp>=1.0.0
+Provides-Extra: dev
+Requires-Dist: mypy>=1.8; extra == 'dev'
+Requires-Dist: pytest-asyncio>=0.23; extra == 'dev'
+Requires-Dist: pytest-mock>=3.12; extra == 'dev'
+Requires-Dist: pytest>=8.0; extra == 'dev'
+Requires-Dist: ruff>=0.2; extra == 'dev'
+Description-Content-Type: text/markdown
+
+# Moonbridge
+
+**Your MCP client just got a team.**
+
+Spawn Kimi K2.5 agents from Claude Code, Cursor, or any MCP client. Run 5 approaches in parallel for the cost of one Claude request.
+
+```bash
+uvx moonbridge
+```
+
+## Quick Start
+
+1. **Install Kimi CLI and authenticate:**
+   ```bash
+   uv tool install --python 3.13 kimi-cli && kimi login
+   ```
+
+2. **Add to MCP config** (`~/.mcp.json`):
+   ```json
+   {
+     "mcpServers": {
+       "moonbridge": {
+         "type": "stdio",
+         "command": "uvx",
+         "args": ["moonbridge"]
+       }
+     }
+   }
+   ```
+
+3. **Use it.** Your MCP client now has `spawn_agent` and `spawn_agents_parallel` tools.
+
+## When to Use Moonbridge
+
+| Task | Why Moonbridge |
+|------|----------------|
+| Parallel exploration | Run 5 approaches simultaneously, pick the best |
+| Frontend/UI work | Kimi excels at visual coding and component design |
+| Tests and documentation | Cost-effective for high-volume tasks |
+| Refactoring | Try multiple strategies in one request |
+
+**Best for:** Tasks that benefit from parallel execution or volume.
+
+## Tools
+
+| Tool | Use case |
+|------|----------|
+| `spawn_agent` | Single task: "Write tests for auth.ts" |
+| `spawn_agents_parallel` | Go wide: 5 agents, 5 approaches, pick the best |
+| `check_status` | Verify Kimi CLI is installed and authenticated |
+
+### Example: Parallel Exploration
+
+```json
+{
+  "agents": [
+    {"prompt": "Refactor to React hooks"},
+    {"prompt": "Refactor to Zustand"},
+    {"prompt": "Refactor to Redux Toolkit"}
+  ]
+}
+```
+
+Three approaches. One request. You choose the winner.
+
+### Tool Parameters
+
+**`spawn_agent`**
+
+| Parameter | Type | Required | Description |
+|-----------|------|----------|-------------|
+| `prompt` | string | Yes | Task description for the agent |
+| `thinking` | boolean | No | Enable reasoning mode (default: false) |
+| `timeout_seconds` | integer | No | Override default timeout (30-3600) |
+
+**`spawn_agents_parallel`**
+
+| Parameter | Type | Required | Description |
+|-----------|------|----------|-------------|
+| `agents` | array | Yes | List of agent configs (max 5) |
+| `agents[].prompt` | string | Yes | Task for this agent |
+| `agents[].thinking` | boolean | No | Enable reasoning for this agent |
+| `agents[].timeout_seconds` | integer | No | Timeout for this agent |
+
+## Response Format
+
+All tools return JSON with these fields:
+
+| Field | Type | Description |
+|-------|------|-------------|
+| `status` | string | `success`, `error`, `timeout`, `auth_error`, or `cancelled` |
+| `output` | string | stdout from Kimi agent |
+| `stderr` | string\|null | stderr if any |
+| `returncode` | int | Process exit code (-1 for timeout/error) |
+| `duration_ms` | int | Execution time in milliseconds |
+| `agent_index` | int | Agent index (0 for single, 0-N for parallel) |
+| `message` | string? | Human-readable error context (when applicable) |
+
+## Configuration
+
+### Environment Variables
+
+| Variable | Description |
+|----------|-------------|
+| `MOONBRIDGE_TIMEOUT` | Default timeout in seconds (30-3600) |
+| `MOONBRIDGE_MAX_AGENTS` | Maximum parallel agents |
+| `MOONBRIDGE_ALLOWED_DIRS` | Colon-separated allowlist of working directories |
+| `MOONBRIDGE_LOG_LEVEL` | Set to `DEBUG` for verbose logging |
+
+## Troubleshooting
+
+### "Kimi CLI not found"
+
+Install the Kimi CLI:
+
+```bash
+uv tool install --python 3.13 kimi-cli
+which kimi
+```
+
+### "auth_error" responses
+
+Authenticate with Kimi:
+
+```bash
+kimi login
+```
+
+### Timeout errors
+
+Increase the timeout for long-running tasks:
+
+```json
+{"prompt": "...", "timeout_seconds": 1800}
+```
+
+Or set a global default:
+
+```bash
+export MOONBRIDGE_TIMEOUT=1800
+```
+
+### Permission denied on working directory
+
+Verify the directory is in your allowlist:
+
+```bash
+export MOONBRIDGE_ALLOWED_DIRS="/path/to/project:/another/path"
+```
+
+### Debug logging
+
+Enable verbose logging:
+
+```bash
+export MOONBRIDGE_LOG_LEVEL=DEBUG
+```
+
+## Platform Support
+
+macOS and Linux only. Windows is not supported.
+
+## License
+
+MIT. See `LICENSE`.

moonbridge-0.2.0/README.md

@@ -0,0 +1,165 @@
+# Moonbridge
+
+**Your MCP client just got a team.**
+
+Spawn Kimi K2.5 agents from Claude Code, Cursor, or any MCP client. Run 5 approaches in parallel for the cost of one Claude request.
+
+```bash
+uvx moonbridge
+```
+
+## Quick Start
+
+1. **Install Kimi CLI and authenticate:**
+   ```bash
+   uv tool install --python 3.13 kimi-cli && kimi login
+   ```
+
+2. **Add to MCP config** (`~/.mcp.json`):
+   ```json
+   {
+     "mcpServers": {
+       "moonbridge": {
+         "type": "stdio",
+         "command": "uvx",
+         "args": ["moonbridge"]
+       }
+     }
+   }
+   ```
+
+3. **Use it.** Your MCP client now has `spawn_agent` and `spawn_agents_parallel` tools.
+
+## When to Use Moonbridge
+
+| Task | Why Moonbridge |
+|------|----------------|
+| Parallel exploration | Run 5 approaches simultaneously, pick the best |
+| Frontend/UI work | Kimi excels at visual coding and component design |
+| Tests and documentation | Cost-effective for high-volume tasks |
+| Refactoring | Try multiple strategies in one request |
+
+**Best for:** Tasks that benefit from parallel execution or volume.
+
+## Tools
+
+| Tool | Use case |
+|------|----------|
+| `spawn_agent` | Single task: "Write tests for auth.ts" |
+| `spawn_agents_parallel` | Go wide: 5 agents, 5 approaches, pick the best |
+| `check_status` | Verify Kimi CLI is installed and authenticated |
+
+### Example: Parallel Exploration
+
+```json
+{
+  "agents": [
+    {"prompt": "Refactor to React hooks"},
+    {"prompt": "Refactor to Zustand"},
+    {"prompt": "Refactor to Redux Toolkit"}
+  ]
+}
+```
+
+Three approaches. One request. You choose the winner.
+
+### Tool Parameters
+
+**`spawn_agent`**
+
+| Parameter | Type | Required | Description |
+|-----------|------|----------|-------------|
+| `prompt` | string | Yes | Task description for the agent |
+| `thinking` | boolean | No | Enable reasoning mode (default: false) |
+| `timeout_seconds` | integer | No | Override default timeout (30-3600) |
+
+**`spawn_agents_parallel`**
+
+| Parameter | Type | Required | Description |
+|-----------|------|----------|-------------|
+| `agents` | array | Yes | List of agent configs (max 5) |
+| `agents[].prompt` | string | Yes | Task for this agent |
+| `agents[].thinking` | boolean | No | Enable reasoning for this agent |
+| `agents[].timeout_seconds` | integer | No | Timeout for this agent |
+
+## Response Format
+
+All tools return JSON with these fields:
+
+| Field | Type | Description |
+|-------|------|-------------|
+| `status` | string | `success`, `error`, `timeout`, `auth_error`, or `cancelled` |
+| `output` | string | stdout from Kimi agent |
+| `stderr` | string\|null | stderr if any |
+| `returncode` | int | Process exit code (-1 for timeout/error) |
+| `duration_ms` | int | Execution time in milliseconds |
+| `agent_index` | int | Agent index (0 for single, 0-N for parallel) |
+| `message` | string? | Human-readable error context (when applicable) |
+
+## Configuration
+
+### Environment Variables
+
+| Variable | Description |
+|----------|-------------|
+| `MOONBRIDGE_TIMEOUT` | Default timeout in seconds (30-3600) |
+| `MOONBRIDGE_MAX_AGENTS` | Maximum parallel agents |
+| `MOONBRIDGE_ALLOWED_DIRS` | Colon-separated allowlist of working directories |
+| `MOONBRIDGE_LOG_LEVEL` | Set to `DEBUG` for verbose logging |
+
+## Troubleshooting
+
+### "Kimi CLI not found"
+
+Install the Kimi CLI:
+
+```bash
+uv tool install --python 3.13 kimi-cli
+which kimi
+```
+
+### "auth_error" responses
+
+Authenticate with Kimi:
+
+```bash
+kimi login
+```
+
+### Timeout errors
+
+Increase the timeout for long-running tasks:
+
+```json
+{"prompt": "...", "timeout_seconds": 1800}
+```
+
+Or set a global default:
+
+```bash
+export MOONBRIDGE_TIMEOUT=1800
+```
+
+### Permission denied on working directory
+
+Verify the directory is in your allowlist:
+
+```bash
+export MOONBRIDGE_ALLOWED_DIRS="/path/to/project:/another/path"
+```
+
+### Debug logging
+
+Enable verbose logging:
+
+```bash
+export MOONBRIDGE_LOG_LEVEL=DEBUG
+```
+
+## Platform Support
+
+macOS and Linux only. Windows is not supported.
+
+## License
+
+MIT. See `LICENSE`.

moonbridge-0.2.0/pyproject.toml

@@ -0,0 +1,65 @@
+[project]
+name = "moonbridge"
+dynamic = ["version"]
+description = "MCP server for spawning Kimi K2.5 agents"
+readme = "README.md"
+requires-python = ">=3.11"
+license = "MIT"
+authors = [
+    {name = "Phaedrus", email = "hello@mistystep.io"}
+]
+keywords = ["mcp", "kimi", "claude", "agent", "ai"]
+classifiers = [
+    "Development Status :: 4 - Beta",
+    "Environment :: Console",
+    "Intended Audience :: Developers",
+    "License :: OSI Approved :: MIT License",
+    "Programming Language :: Python :: 3",
+    "Programming Language :: Python :: 3.11",
+    "Programming Language :: Python :: 3.12",
+    "Programming Language :: Python :: 3.13",
+]
+dependencies = [
+    "mcp>=1.0.0",
+]
+
+[project.optional-dependencies]
+dev = [
+    "pytest>=8.0",
+    "pytest-asyncio>=0.23",
+    "pytest-mock>=3.12",
+    "mypy>=1.8",
+    "ruff>=0.2",
+]
+
+[project.scripts]
+moonbridge = "moonbridge.server:main"
+
+[project.urls]
+Homepage = "https://github.com/misty-step/moonbridge"
+Repository = "https://github.com/misty-step/moonbridge"
+Issues = "https://github.com/misty-step/moonbridge/issues"
+
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[tool.pytest.ini_options]
+asyncio_mode = "auto"
+testpaths = ["tests"]
+
+[tool.mypy]
+python_version = "3.11"
+strict = true
+# MCP library decorators are not fully typed
+disable_error_code = ["no-untyped-call", "untyped-decorator"]
+
+[tool.ruff]
+target-version = "py311"
+line-length = 100
+
+[tool.ruff.lint]
+select = ["E", "F", "I", "UP", "B", "SIM"]
+
+[tool.hatch.version]
+path = "src/moonbridge/__init__.py"

moonbridge-0.2.0/release-please-config.json

@@ -0,0 +1,23 @@
+{
+  "$schema": "https://raw.githubusercontent.com/googleapis/release-please/main/schemas/config.json",
+  "release-type": "python",
+  "packages": {
+    ".": {
+      "package-name": "moonbridge",
+      "extra-files": [
+        {
+          "type": "generic",
+          "path": "src/moonbridge/__init__.py"
+        }
+      ]
+    }
+  },
+  "changelog-sections": [
+    {"type": "feat", "section": "Features"},
+    {"type": "fix", "section": "Bug Fixes"},
+    {"type": "perf", "section": "Performance"},
+    {"type": "docs", "section": "Documentation", "hidden": true},
+    {"type": "chore", "section": "Miscellaneous", "hidden": true},
+    {"type": "ci", "section": "Miscellaneous", "hidden": true}
+  ]
+}

moonbridge-0.2.0/src/moonbridge/__init__.py

@@ -0,0 +1,9 @@
+"""MCP server for spawning Kimi K2.5 agents."""
+
+from __future__ import annotations
+
+__version__ = "0.2.0"
+
+from .server import main, run, server
+
+__all__ = ["__version__", "main", "run", "server"]

moonbridge-0.2.0/src/moonbridge/py.typed

@@ -0,0 +1 @@
+