fluid-mcp

# Fluid MCP [![CI][ci-badge]][ci-workflow] [ci-badge]: https://github.com/botnetbuddies/fluid-mcp/actions/workflows/ci.yml/badge.svg [ci-workflow]: https://github.com/botnetbuddies/fluid-mcp/actions/workflows/ci.yml Fluid MCP is a standalone MCP stdio server that renders operator-reviewed commands from the [`botnetbuddies/cheats`](https://github.com/botnetbuddies/cheats) with CheatMD ([website](https://cheatmd.dev), [repository](https://github.com/cheatmd-dev/cheatmd)). It keeps a cached cheats checkout and uses imported CheatMD Go packages to parse, index, lint, and render commands in-process. Render/search surfaces remain non-executing. ## First-use flow 1. Install or run Fluid MCP with either the local Go binary or Docker. 2. Add the matching command to your MCP client configuration. 3. Start the client and use Fluid MCP tools to search, inspect, render, review, and scope-check commands. 4. Keep render-only output under human operator review. ## Install or run Requirements for source installs: - Go 1.26.3+ - `git` on `PATH` ### Local binary Install the latest released source build: ```bash go install github.com/botnetbuddies/fluid-mcp/cmd/fluid-mcp@latest ``` Install the current pinned release: ```bash go install github.com/botnetbuddies/fluid-mcp/cmd/fluid-mcp@v0.2.1 ``` Prebuilt release archives and SHA-256 checksums are published at [GitHub Releases](https://github.com/botnetbuddies/fluid-mcp/releases/tag/v0.2.1). Run the installed server over stdio: ```bash fluid-mcp ``` Run from a local checkout: ```bash go run ./cmd/fluid-mcp ``` ### Docker Build the image: ```bash docker build -t fluid-mcp . ``` Run with a persistent cheats cache: ```bash docker run -i --rm -v fluid-mcp-cache:/cache fluid-mcp ``` Smoke-test startup without an MCP client: ```bash docker run -i --rm -v fluid-mcp-cache:/cache fluid-mcp < /dev/null ``` The smoke test exits when stdin closes. ## Configure your MCP client Fluid MCP speaks MCP over stdio. Pick the configuration that matches how you run it. Fluid MCP writes diagnostics to stderr so stdout stays reserved for MCP protocol traffic. ### Local binary configuration Use this when `fluid-mcp` is installed on your `PATH`: ```json { "command": "fluid-mcp", "args": [] } ``` ### Docker configuration Use this when the MCP client should launch the Docker container: ```json { "command": "docker", "args": ["run", "-i", "--rm", "-v", "fluid-mcp-cache:/cache", "fluid-mcp"] } ``` First startup needs network access to clone the cheats repository. Later starts reuse the cache and update it when GitHub is reachable. See the [configuration guide](docs/configuration.md) for flags, environment variables, cache behavior, and troubleshooting. ## First safe use Typical render-only flow: 1. Search for relevant cheats, methods, or chains. 2. Inspect the selected entry and its source/provenance metadata. 3. Provide required variables and optional engagement scope. 4. Review the rendered command or recipe. 5. Run anything outside Fluid MCP only when it is authorized and appropriate. Scope-aware rendering can block command generation before command text is returned. Pass `engagement_scope` plus `scope_context` to generation tools, or call `evaluate_engagement_scope` directly before rendering. Scope checks are guardrails for operator review; they are not a substitute for reading the signed ROE. For the full safe workflow, scope model, methods/chains, and evidence reporting, read the [operator workflow guide](docs/operator-workflow.md). For the complete MCP tool list and response metadata, read the [tool reference](docs/tool-reference.md). ## Documentation - [Configuration and troubleshooting](docs/configuration.md) - [Safe operator workflow](docs/operator-workflow.md) - [MCP tool reference](docs/tool-reference.md) - [Verification and releases](docs/release.md) - [Manual MCP smoke tests](PILOT_TESTING.md) - [Changelog](CHANGELOG.md) ## Contributing, security, license - Contributions: [CONTRIBUTING.md](CONTRIBUTING.md) - Security reporting and operational guidance: [SECURITY.md](SECURITY.md) - License: MIT, see [LICENSE](LICENSE)