Mirror notice: This repository is a one-way published export of a privately hosted project. History is squashed into sync snapshots, and pull requests cannot be merged here directly. Open an issue instead. Changes land in the private source and are re-exported.

MagicTools is a local Model Context Protocol (MCP) orchestrator and gateway. It starts and supervises downstream stdio MCP servers, indexes their tools, aligns natural-language intent to those tools, proxies calls, and exposes fleet health, search, pipeline, and observability features through one MCP entry point.

Use the default stdio mode for one MCP client process. Use the background service with either the stdio proxy or direct Streamable HTTP when multiple client windows must share one datastore and one downstream fleet.

Linux or macOS:

curl -fsSL https://github.com/maccavelli/mcp-server-magictools/releases/latest/download/install.sh | sh

Windows PowerShell:

irm https://github.com/maccavelli/mcp-server-magictools/releases/latest/download/install.ps1 | iex

The installer verifies SHA256SUMS and places only the binary. It does not run init or configure, and it does not install or start a service. Published targets are Linux amd64, macOS arm64, and Windows amd64.

• What it does
• I want to
• Quick start
• Runtime model
• Supported platforms
• Documentation library
• Current limitations
• Project verification

• Manages downstream MCP server processes from servers.yaml.
• Presents native MagicTools tools plus namespaced downstream tools to clients.
• Finds tools with Bleve lexical search and optional HNSW vector search.
• Executes downstream tools through a schema-validating proxy.
• Supports critical and deferred fleet boot, health monitoring, restart, and runtime configuration reload.
• Provides an optional multi-server DAG pipeline when Recall, Brainstorm, and Go Modernizer are online.
• Exposes a terminal dashboard backed by a persistent telemetry ring.
• Can provide a shared, authenticated LLM backplane to managed servers.

Initialize the three YAML files:

mcp-server-magictools init

Edit servers.yaml and replace the example paths for the downstream servers you actually have. The generated registry contains examples, not a ready-to-run fleet.

Optionally configure LLM and embedding providers in an interactive terminal:

mcp-server-magictools configure

Then point an MCP client at the binary:

{
  "mcpServers": {
    "magictools": {
      "command": "/absolute/path/to/mcp-server-magictools",
      "args": ["serve"]
    }
  }
}

serve is the default command, but keeping it explicit makes client configuration and process listings clearer. Use an absolute executable path; GUI clients commonly inherit a restricted PATH.

MCP client
    |
    +-- stdio: client starts `magictools serve`
    |
    +-- shared service
          +-- stdio client starts `magictools proxy`
          +-- HTTP client uses http://localhost:48080/mcp
                         |
                    MagicTools
                  /      |       \
             Badger    search    managed stdio MCP servers
             source   Bleve/HNSW

The Badger datastore is single-owner. Do not start two direct stdio instances against the same --db path. For multiple client windows, install one background service and connect each client through proxy or Streamable HTTP.

In service mode, local IPC uses a Unix-domain socket on Linux/macOS or a user-scoped named pipe on Windows, with authenticated loopback TCP fallbacks. The IDE-facing HTTP endpoint is intentionally unauthenticated and must remain loopback-only.

Release binaries are cgo-free and do not require Go at runtime. Go 1.26.5 is required to build this repository. A managed server or pipeline tool may impose its own runtime requirements; for example, Go-aware mutation tools can require MCP_GO_BIN_PATH.

• Getting started
• Platform installation
• Client integration
• Services and transports
• Configuration
• CLI reference
• MCP tools and orchestration
• Dashboard and observability
• Operations and security
• Repository assessment

The existing architectural decision and implementation-plan artifacts remain in docs/.

• The generated servers.yaml contains disabled examples with placeholder executable paths. It must be edited for the local machine.
• The datastore lock prevents concurrent direct instances using the same data directory.
• dash --find initializes search but does not currently return query results.
• Pipeline tools are visible but return pipeline_disabled unless Recall, Brainstorm, and Go Modernizer are all online.
• The IDE-facing service endpoint has no bearer authentication. The runtime rejects non-loopback binds unless explicitly overridden; do not override that guard on an untrusted network.
• There is no first-class backup or restore command for the MagicTools datastore. Stop the service and copy the config and data directories.

See the repository assessment for the complete audit, including known CLI, configuration, and repository hygiene issues.

The CI workflow runs on every branch push and pull request. Linux owns format, module-tidiness, vet, cgo-free tests, lint, and installer tests; macOS arm64 and Windows amd64 also build, vet, and execute the complete Go test suite natively. Semver tags (vX.Y.Z) build, checksum, smoke-test, and publish all three release targets.

Local verification:

make fmt
go vet ./...
CGO_ENABLED=0 go test ./...
make lint
make build-all