fluently-mcp-server

MCP server for Fluently — exposes knowledge retrieval and contribution tools so any AI agent can find, reason over, and extend collaboration cycles across any registered framework, without hardcoded scores.

Framework-agnostic. Bundles the AI Fluency 4D Framework as the default. Any framework with named dimensions can be registered.

Works with Claude, GPT-4o, Gemini, Mistral, Llama, GitHub Copilot, Cursor, Cline, and any other MCP-compatible agent.

Install

npm install -g fluently-mcp-server

Requires Node.js 20+.

Wire to your agent

The same config block works for any MCP-compatible client. The server speaks stdio.

Claude Desktop (~/Library/Application Support/Claude/claude_desktop_config.json on Mac, %APPDATA%\Claude\claude_desktop_config.json on Windows):

{
  "mcpServers": {
    "fluently": { "command": "fluently-mcp-server" }
  }
}

Claude Code (~/.claude/settings.json):

{
  "mcpServers": {
    "fluently": { "command": "fluently-mcp-server" }
  }
}

VS Code Copilot / Continue / Cursor / Cline — paste the same block into your extension's MCP settings.

Tools

| Tool | Purpose | |------|---------| | list_domains | List available knowledge domains and cycle counts | | find_relevant_cycles | Retrieve ranked candidate cycles for a task — agent reasons, no false-precision scores | | get_cycle_detail | Full cycle by ID — all dimension fields for its registered framework | | get_dimension_guidance | Antipatterns + examples for one dimension across all cycles | | refresh_knowledge | Re-fetch from the connector without restarting the server | | contribute_cycle | Validate a new cycle and submit it to the knowledge source |

Connectors

Set FLUENTLY_CONNECTOR to choose where knowledge comes from.

github-public (default)

Fetches live from the public community repo. No auth required.

# Default — no configuration needed
fluently-mcp-server

# Point to a public fork
FLUENTLY_CONNECTOR=github-public \
FLUENTLY_GITHUB_REPO=your-org/your-fork \
fluently-mcp-server

contribute_cycle returns a YAML template + PR instructions for the community repo.

github-private

Fetches from a private GitHub repo. Requires a PAT with repo scope. contribute_cycle creates branches and opens PRs automatically.

FLUENTLY_CONNECTOR=github-private \
FLUENTLY_GITHUB_REPO=your-org/your-private-knowledge \
FLUENTLY_GITHUB_TOKEN=ghp_xxx \
fluently-mcp-server

local

Reads from a local directory — ideal for development, air-gapped environments, or building private cycles before publishing.

FLUENTLY_CONNECTOR=local \
FLUENTLY_LOCAL_PATH=/path/to/your/knowledge \
fluently-mcp-server

contribute_cycle writes YAML directly to the configured directory.

sql (planned)

PostgreSQL / SQLite. Coming in a future release.

nosql (planned)

MongoDB. Coming in a future release.

Environment variables

| Variable | Default | Description | |----------|---------|-------------| | FLUENTLY_CONNECTOR | github-public | Connector to use | | FLUENTLY_GITHUB_REPO | Fluently-Org/fluently | GitHub repo (owner/repo) | | FLUENTLY_GITHUB_BRANCH | main | Branch to read from | | FLUENTLY_GITHUB_TOKEN | (none) | Required for private repos and automated PRs | | FLUENTLY_LOCAL_PATH | ./knowledge | Local knowledge directory (local connector only) |

Why no scores?

Numeric scores (e.g., "delegation: 34/100") are biased by writing style — two people describing the same workflow in different vocabulary get different numbers.

The server does retrieval: it surfaces the most relevant cycles using keyword similarity and returns them for your agent to reason over in context. You assess fit. That's more accurate, and it adapts to what your situation actually needs rather than returning a false-precision number.

When to use this vs. GitHub MCP

If you only need occasional lookups from the public knowledge base, the raw index.json is fetchable without auth via any HTTP tool.

Use this server when you need:

• Private knowledge that stays in your org
• Isolation from the community repo
• Structured tools (domain listing, dimension guidance, contribute flow)
• Automatic sync and refresh without restarting your agent

Links

• Knowledge Base — fluently-org.github.io/fluently/knowledge.html
• Contribute a cycle — fluently-org.github.io/fluently/contribute.html
• GitHub repo — github.com/Fluently-Org/fluently
• CLI — npmjs.com/package/fluently-cli
• Scorer library — npmjs.com/package/fluently-scorer

License

MIT — code and bundled knowledge cycles.