ArtCraft MCP Unified Router

Restored V11 release: The full Windows launcher and unified router from the original V11 archive have been restored. The launcher includes GUI launching in control mode, app selection, port checks, tunnel configuration and management, dashboard, and logging. Windows integration still requires testing on your PC. See RESTORATION_NOTES.md.

A community project for running multiple ArtCraft desktop applications behind a single Model Context Protocol (MCP) gateway, with a Windows launcher and dynamic tool discovery.

This is a community integration, not an official ArtCraft or OpenAI release. You must install the applications and configure your own credentials and paths.

Architecture

ChatGPT / OpenCode / other MCP client
                 |
         MCP tools/list, tools/call
                 |
      Remote tunnel (optional)
                 |
        Unified ArtCraft Router
         /         |         \
   GridCraft   SolidCraft   DeckCraft / other apps
         \         |         /
          Local application APIs

Application API: the underlying command engine that actually edits a workbook, model, or presentation.

MCP server: a wrapper that advertises callable operations as tools with JSON input schemas. MCP clients discover these with tools/list and invoke them with tools/call.

Unified router: discovers each selected application's MCP tools, aggregates the catalog, and forwards calls to the appropriate application.

Tunnel: provides transport from a remote MCP client/control plane to your local router. A tunnel does not generate tools or replace the application API.

ChatGPT plugin/connection: makes permitted tools visible to ChatGPT. The client may cache the tool catalog; reconnect after updates if new tools do not appear.

Related MCP server: Git-Fabric Gateway

Requirements

• Windows 10/11 and Python 3.10 or later.

• ArtCraft application(s) and their matching CLI/MCP servers installed locally.

• For local use, an MCP-capable client.

• For remote ChatGPT use, a compatible ChatGPT connection, tunnel client, authorized tunnel ID, and control-plane API credential. Availability depends on your ChatGPT/workspace setup.

Quick start

1. Clone the repository or download the ZIP.

2. Configure the paths for installed ArtCraft applications in artcraft_unified_launcher_v9.py and artcraft_router.json.

3. Disable applications not installed on your computer.

4. Start the Windows launcher:

   python artcraft_unified_launcher_v9.py

5. Start the selected application GUIs and their MCP endpoints.

6. Verify that each application's MCP server is reachable.

7. Start the unified router or tunnel using your local configuration.

8. Confirm the tool catalog through the router's status, catalog, and refresh functions.

9. Connect an MCP-compatible client and test a read-only command before allowing modifications.

Download the official OpenAI Secure MCP Tunnel client

• Download the latest tunnel-client release (Windows, macOS, Linux)

• OpenAI tunnel-client source code

• Official Secure MCP Tunnel setup guide

• OpenAI Platform tunnel management

On Windows, open the latest release, download the appropriate windows-amd64 ZIP for most Intel/AMD PCs, extract it, and locate tunnel-client.exe. In PowerShell run .\\tunnel-client.exe help quickstart for supported setup instructions. Create your own tunnel ID and credentials in OpenAI Platform; never reuse another person's values.

Generate your own OpenAI API key

1. Sign in to the OpenAI API Keys page.

2. Select the appropriate project and choose Create new secret key.

3. Copy the key securely when it is displayed. Never commit it to this repository.

4. For a local PowerShell session, set $env:CONTROL_PLANE_API_KEY = "YOUR_OWN_KEY" only if your tunnel setup specifically requires an OpenAI API key for that variable.

Important: OpenAI API keys and ChatGPT subscriptions are separate. A standard OpenAI API key may not be sufficient to authenticate a particular tunnel/control-plane deployment; use the credential required by your tunnel setup.

OpenAI tunnel and API setup (optional)

A ChatGPT subscription is not an OpenAI API key. Obtain tunnel credentials through the supported control-plane onboarding process; do not commit secrets to GitHub.

Example control-plane configuration fragment (adapt to the installed tunnel-client version and its documented YAML format):

config_version: 1
control_plane:
  base_url: "https://api.openai.com"
  tunnel_id: "REPLACE_WITH_YOUR_OWN_TUNNEL_ID"
  api_key: "env:CONTROL_PLANE_API_KEY"

In PowerShell:

$env:CONTROL_PLANE_API_KEY = "YOUR_OWN_API_KEY"
.\tunnel-client.exe run --profile YOUR_PROFILE

This fragment is not a complete tunnel profile. Configure its MCP backend to launch or connect to the unified router, not an individual app, when aggregation is desired. Use the official tunnel-client documentation for its exact transport and backend fields. Do not expose unauthenticated local ports publicly.

Connect ChatGPT Web, OpenCode, Claude Desktop, and Claude Web

One ArtCraft command engine, different MCP transports. Each Craft app still needs its own installed GUI and compatible local MCP/control-mode interface. The unified router aggregates these interfaces; the AI client chooses how to reach the router.

ChatGPT Web: OpenAI Secure MCP Tunnel

ChatGPT Web
  → OpenAI Secure MCP Tunnel (authorized tunnel ID / credentials)
  → ArtCraft Unified MCP Router (local Windows PC)
  → selected GridCraft / SolidCraft / DeckCraft MCP server
  → Craft GUI launched in control mode

Install the official OpenAI tunnel-client, configure a valid control-plane profile and its MCP backend according to the official documentation, and connect through a supported ChatGPT MCP integration. The tunnel is transport, not the unified router or an application MCP server. Installing the tunnel alone does not launch Craft applications or configure their paths.

OpenCode on Windows: direct local MCP, no tunnel

Configure the local MCP server in opencode.json (merge with existing settings):

{
  "mcp": {
    "artcraft": {
      "type": "local",
      "command": [
        "python",
        "C:\\ArtCraft\\artcraft_unified_router.py",
        "--config",
        "C:\\ArtCraft\\artcraft_router.json"
      ],
      "enabled": true
    }
  }
}

Replace C:\ArtCraft with your installation directory. OpenCode launches the stdio router locally; the router dispatches to the configured app MCP servers. See OpenCode MCP documentation for the supported configuration schema in your installed version. No OpenAI tunnel or public IP is needed.

Claude Desktop: direct local MCP, no tunnel

Add a local stdio server to %APPDATA%\Claude\claude_desktop_config.json (merge into existing mcpServers):

{
  "mcpServers": {
    "artcraft": {
      "command": "python",
      "args": [
        "C:\\ArtCraft\\artcraft_unified_router.py",
        "--config",
        "C:\\ArtCraft\\artcraft_router.json"
      ]
    }
  }
}

Restart Claude Desktop after changing the file. This is Claude Desktop, not Claude in a browser.

Claude Web: secure remote HTTP MCP endpoint required

Claude Web (claude.ai)
  → HTTPS remote MCP endpoint with appropriate authentication
  → HTTP MCP bridge / Streamable HTTP server on your Windows PC
  → ArtCraft Unified MCP Router
  → Craft app MCP server → Craft GUI in control mode

Claude Web cannot directly start a Windows stdio command on your PC. A third-party network tunnel (for example, Cloudflare Tunnel) can provide HTTPS reachability, but a tunnel by itself does not convert stdio MCP to HTTP MCP. You must also run a compatible HTTP MCP server/bridge supporting the transport accepted by Claude's custom connectors, and secure it with authentication and access controls. Then add the remote connector in Claude's connector settings, subject to plan and workspace availability.

Current repository limitation: This project currently provides a stdio router. It does not include a tested Claude Web HTTP bridge, Cloudflare Tunnel configuration, or authentication implementation. Do not publish an unauthenticated MCP endpoint to the internet.

Recommended cross-client architecture

                  ┌─ ChatGPT Web ─ OpenAI Secure MCP Tunnel ─┐
ArtCraft Router ←─┼─ OpenCode / Claude Desktop ─ local stdio ┤
                  └─ Claude Web ─ HTTPS + authenticated HTTP bridge ┘
                           |
                  app MCP servers / GUI control mode

The diagram shows alternative frontends into one router, not a requirement to run all connections at once. Keep Craft-specific commands and discovery in the shared router; add transport adapters separately. After application updates, refresh tool discovery and reconnect a client if its tool catalog remains cached.

What the Python files actually do

The repository has two different Python programs. They are not interchangeable.

artcraft_unified_router.py — the MCP engine (required)

This is the stdio MCP server used by compatible MCP clients or launched by a correctly configured tunnel backend. It:

1. Reads artcraft_router.json and selects only apps with enabled: true.

2. Starts each selected application's configured MCP child process (not necessarily its GUI).

3. Sends MCP initialize and tools/list requests to discover available commands.

4. Publishes one combined tool catalog, with namespaced tools such as gridcraft__<tool_name>, plus helper tools: artcraft_status, artcraft_apps, artcraft_tools, artcraft_catalog, artcraft_refresh, and artcraft_execute.

5. Forwards tools/call requests to the correct child MCP server and returns its response to the calling AI client.

6. Can explicitly refresh/reconnect tools; automatic notification-based discovery is not implemented.

AI MCP client (or tunnel MCP backend)
  → artcraft_unified_router.py
  → GridCraft / SolidCraft / DeckCraft child MCP server
  → application's local control interface / GUI

Important: The router does not itself launch Craft GUIs in control mode, implement CAD/spreadsheet operations, or expose an HTTP endpoint. Those capabilities depend on the installed application MCP server and its configuration. Its configured child command must correctly connect to the corresponding running app.

artcraft_unified_launcher_v9.py — Windows configuration GUI (optional)

This is a lightweight Tkinter interface for managing the setup. It currently provides application enable/disable checkboxes, saves selections to artcraft_router.json, lets you choose a tunnel executable and profile, and offers basic tunnel start/stop controls and log messages.

Current limitations of the published launcher:

• Start local router prints the command for an MCP client to launch; it does not start a standalone router process. This is intentional for stdio MCP, where the client/tunnel should own the process.

• It does not currently start the Craft application GUIs in --control mode.

• Its tunnel launch argument (--profile-file) has not been validated against the official tunnel-client CLI; check your installed version's help output.

• This is a simplified launcher, not the original full-featured V11 launcher used in the project owner's working setup.

Which files are required?

Validation status: The project owner reports an end-to-end GridCraft test of their existing local tunnel setup. That does not yet establish that the simplified Python files published here reproduce the same result on a clean installation. Before a stable release, align the published launcher/router with the tested implementation and run a fresh end-to-end installation test.

Dynamic discovery when applications update

1. Install the updated application and matching MCP server.

2. Restart that server if required.

3. Refresh the unified router's MCP tool catalog.

4. Verify the new tool in tools/list.

5. Reconnect ChatGPT or your MCP client if its list remains stale.

A stable execute_command MCP tool can often invoke newly added ribbon/menu commands by command ID, even when no new top-level MCP tool was added. Automatic refresh is not guaranteed by every client.

Testing

Run from the project root:

python -m unittest discover -p "test_router_v*.py"

Passing unit tests does not verify that an actual GUI, tunnel, or ChatGPT integration is functioning.

Disclaimer and responsibility

Use at your own risk. This is an independent, community-maintained project provided "AS IS", without warranties of any kind, to the extent permitted by applicable law. The project owner and contributors are not responsible or liable for losses, damages, data loss, corrupted files, business interruption, security incidents, or other consequences arising from installing, configuring, or using this software, to the extent permitted by applicable law. Review and back up important work before allowing AI-driven tools to modify files or applications. This notice supplements, and does not replace, the terms in the MIT License.

Keep credentials private

NEVER share or publish your API keys, tunnel credentials, access tokens, passwords, or other secrets. In particular:

• Do not commit secrets to GitHub, paste them into public issues, screenshots, logs, or shared configuration files.

• Use environment variables or a secure secrets manager; keep local credential files out of version control.

• Treat tunnel IDs and endpoint details as sensitive configuration where appropriate; restrict access to your MCP endpoints and GUI control ports.

• If a secret is exposed, revoke or rotate it immediately and review access logs.

Security

• Replace example paths, ports, and tunnel identifiers with your own.

• Keep local MCP and GUI control endpoints on 127.0.0.1 where possible.

• Never commit tokens, API keys, machine-specific generated YAML, logs, or personal file paths.

• Restrict write/destructive MCP tools to trusted users.

• Revoke any accidentally exposed credential immediately.

Repository files

• artcraft_unified_router.py: unified MCP tool aggregation and dispatch.

• artcraft_unified_launcher_v9.py: Windows launcher.

• artcraft_router.json: configurable application registry.

• test_router_v10.py, test_router_v11.py: unit tests.

• .gitignore, LICENSE: project hygiene and licensing.

License

MIT — see LICENSE.

Contributions, bug reports, and compatibility updates are welcome.