feat(mcp-server): connector-driven architecture with Agent-in-the-Loop retrieval

- Add KnowledgeConnector interface with 5 implementations: github-public
  (default, no auth, live fetch from raw.githubusercontent.com), github-private
  (auto PR via GitHub REST API), local (filesystem), sql/nosql (planned stubs)
- Rewrite index.ts: 6 tools (list_domains, find_relevant_cycles, get_cycle_detail,
  get_dimension_guidance, refresh_knowledge, contribute_cycle); no numeric scores
  exposed — agent reasons over ranked keyword-similarity candidates
- 1-hour TTL cache with bundled knowledge as offline fallback
- Transport connected before background preload to avoid missed stdin
- Add KNOWLEDGE.md for agents using GitHub MCP path (self-documenting knowledge base)
- Bump cli and mcp-server to 0.1.3

Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>

Author: faical-yannick-congo

KNOWLEDGE.md

@@ -0,0 +1,105 @@
+# Fluently Knowledge Base
+
+This document is a navigation guide for agents and humans interacting with the Fluently 4D knowledge base — either directly via GitHub MCP or through a configured Fluently MCP server.
+
+## What is a 4D cycle?
+
+A **Fluently 4D cycle** is a validated pattern for a specific AI-assisted workflow. It describes four dimensions of good human-AI collaboration:
+
+| Dimension | Question it answers |
+|---|---|
+| **Delegation** | Who owns the decision — human, AI, or both? What level of autonomy is appropriate? |
+| **Description** | How should the task be framed so AI understands context fully? |
+| **Discernment** | How do you evaluate whether the AI output is trustworthy? When do you push back? |
+| **Diligence** | What human accountability is required after AI is involved? Who signs off? |
+
+Each dimension includes:
+- `description` — what good looks like
+- `example` — a concrete, real-world instance
+- `antipattern` — what to avoid
+
+## Knowledge base structure
+
+```
+knowledge/
+├── index.json                          ← pre-built index of all cycles (fetch this first)
+├── coding-code-review-triage.yaml      ← individual cycle files
+├── coding-test-case-generation.yaml
+├── writing-content-development.yaml
+└── ...
+```
+
+File naming: `{domain}-{id}.yaml`
+
+## index.json format
+
+```json
+{
+  "entries": [
+    {
+      "id": "code-review-triage",
+      "title": "Code Review Triage",
+      "domain": "coding",
+      "tags": ["code-review", "triage", "automation"],
+      "contributor": "Dakan & Feller",
+      "version": "1.0.0",
+      "summary": "...",
+      "dimensions": {
+        "delegation":  { "description": "...", "example": "...", "antipattern": "..." },
+        "description": { "description": "...", "example": "...", "antipattern": "..." },
+        "discernment": { "description": "...", "example": "...", "antipattern": "..." },
+        "diligence":   { "description": "...", "example": "...", "antipattern": "..." }
+      },
+      "score_hints": { "delegation": 0.2, "description": 0.3, "discernment": 0.3, "diligence": 0.2 }
+    }
+  ]
+}
+```
+
+## Available domains
+
+coding · writing · research · education · legal · healthcare · general
+
+## How to find a relevant cycle (GitHub MCP path)
+
+1. Fetch `knowledge/index.json` — this gives you all cycles in one read
+2. Reason over the entries to find the best match for the task at hand
+3. Fetch the specific YAML file for full dimension detail if needed
+
+Raw URL (no auth required — public repo):
+```
+https://raw.githubusercontent.com/faical-yannick-congo/fluently/main/knowledge/index.json
+```
+
+## How to contribute a new cycle (GitHub MCP path)
+
+Contributions require a GitHub token. The cycle must:
+1. Follow the YAML schema (all 4 dimensions, each with description + example + antipattern)
+2. Have a unique `id` (kebab-case slug)
+3. Belong to one of the supported domains
+4. Include `score_hints` that sum to 1.0
+
+Steps:
+1. Fork https://github.com/faical-yannick-congo/fluently
+2. Add your YAML to `knowledge/{domain}-{id}.yaml`
+3. Open a pull request — CI will validate the schema automatically
+
+## How to use the Fluently MCP server instead
+
+Install and run:
+```bash
+npm install -g fluently-mcp-server
+4d-mcp-server
+```
+
+Configure in your MCP client:
+```json
+{
+  "mcpServers": {
+    "fluently": { "command": "4d-mcp-server" }
+  }
+}
+```
+
+Default connector: `github-public` (fetches live from this repo, no auth needed).
+For private knowledge, see `packages/mcp-server/README.md`.

packages/cli/package.json

@@ -1,6 +1,6 @@
 {
   "name": "fluently-cli",
-  "version": "0.1.2",
+  "version": "0.1.3",
   "main": "src/index.ts",
   "bin": {
     "fluent": "dist/index.js"

packages/mcp-server/README.md

@@ -1,143 +1,125 @@
-# @fluently/mcp-server
+# fluently-mcp-server
 
-MCP (Model Context Protocol) server for the Fluently AI Fluency 4D Framework. Exposes tools for scoring human-AI collaboration quality across the four dimensions: Delegation, Description, Discernment, and Diligence.
+MCP server for the Fluently 4D Framework. Exposes knowledge retrieval and contribution tools so AI agents can find, reason over, and extend Fluently 4D cycles.
 
-## Installation
-
-Install as a workspace dependency:
-
-```bash
-npm install
-```
-
-## Building
-
-```bash
-npm run build
-# or in watch mode
-npm run dev
-```
-
-## Running the Server
-
-### Stdio Transport (Local Use)
-
-The server runs on stdio by default, suitable for local IDE/editor integration:
+## Install
 
 ```bash
-npm start
-# or directly
-node dist/bin.js
+npm install -g fluently-mcp-server
+4d-mcp-server
 ```
 
-The server will write logs to stderr and protocol messages to stdout.
+## Wire to Claude Desktop
 
-### HTTP Transport (Optional Deployment)
+`~/Library/Application Support/Claude/claude_desktop_config.json` (Mac) or `%APPDATA%\Claude\claude_desktop_config.json` (Windows):
 
-To run the server over HTTP (for remote use, though not yet enabled by default), you would modify `src/index.ts` to use `HTTPServerTransport` instead:
-
-```typescript
-import { HTTPServerTransport } from "@modelcontextprotocol/sdk/server/http.js";
-
-const transport = new HTTPServerTransport({
-  host: "localhost",
-  port: 3000,
-});
+```json
+{
+  "mcpServers": {
+    "fluently": { "command": "4d-mcp-server" }
+  }
+}
 ```
 
-Then rebuild and run.
+## Wire to Claude Code
 
-## Configuration
-
-### .mcp.json
-
-The root `.mcp.json` file enables this server in compatible MCP clients:
+In your `settings.json`:
 
 ```json
 {
   "mcpServers": {
-    "fluently": {
-      "command": "node",
-      "args": ["./packages/mcp-server/dist/bin.js"]
-    }
+    "fluently": { "command": "4d-mcp-server" }
   }
 }
 ```
 
 ## Tools
 
-### 1. compare_problem_space
-
-Finds the top 3 similar past 4D plays from the knowledge base.
+| Tool | Purpose |
+|---|---|
+| `list_domains` | List available domains and cycle counts |
+| `find_relevant_cycles` | Retrieve ranked candidate cycles for a task (no scores — agent reasons) |
+| `get_cycle_detail` | Full 4D cycle by ID |
+| `get_dimension_guidance` | Antipatterns + examples for a dimension across all cycles |
+| `refresh_knowledge` | Re-fetch from the connector without restarting |
+| `contribute_cycle` | Validate and submit a new cycle to the knowledge source |
 
-**Inputs:**
-- `task_description` (string, required): Description of the problem or task
-- `domain` (string, optional): Filter by domain (coding, writing, research, etc.)
+## Connectors
 
-**Output:** Array of similar knowledge entries with similarity scores
+The server fetches knowledge from a configured source. Set `FLUENTLY_CONNECTOR` to choose.
 
-### 2. score_delegation
+### github-public (default)
 
-Scores the Delegation and Description dimensions with improvement advice.
+Fetches live from the public Fluently community repo. No auth required. Points to `faical-yannick-congo/fluently` by default.
 
-**Inputs:**
-- `task` (string, required): The task to evaluate
-- `delegation_intent` (string, required): How you intend to delegate (automated, augmented, agentic)
+```bash
+# Default — no config needed
+4d-mcp-server
 
-**Output:** Delegation + Description scores with specific improvement recommendations
+# Point to a public fork
+FLUENTLY_CONNECTOR=github-public \
+FLUENTLY_GITHUB_REPO=your-org/your-public-fork \
+4d-mcp-server
+```
 
-### 3. evaluate_discernment
+Contributing requires opening a PR manually (YAML + instructions returned by `contribute_cycle`).
 
-Evaluates discernment for an AI output: hallucination risk, confidence calibration, and human review requirements.
+### github-private
 
-**Inputs:**
-- `ai_output` (string, required): The AI-generated output to evaluate
-- `original_task` (string, required): The original task given to the AI
+Fetches from a private GitHub repo via the GitHub API. Requires a personal access token with `repo` scope. `contribute_cycle` creates branches and PRs automatically.
 
-**Output:** Discernment score, hallucination risk percentage, confidence calibration, and human review guidance
+```bash
+FLUENTLY_CONNECTOR=github-private \
+FLUENTLY_GITHUB_REPO=your-org/your-private-knowledge \
+FLUENTLY_GITHUB_TOKEN=ghp_xxx \
+4d-mcp-server
+```
 
-### 4. check_diligence
+### local
 
-Returns a diligence checklist: transparency requirements, accountability steps, and disclosure needs.
+Reads from a local directory. Ideal for development, air-gapped environments, or building private cycles before committing.
 
-**Inputs:**
-- `task` (string, required): The task to evaluate
-- `domain` (string, required): The domain context
+```bash
+FLUENTLY_CONNECTOR=local \
+FLUENTLY_LOCAL_PATH=/path/to/your/knowledge \
+4d-mcp-server
+```
 
-**Output:** Structured checklist for maintaining accountability and transparency
+`contribute_cycle` writes YAML files directly to the configured directory.
 
-### 5. get_4d_score
+### sql _(planned)_
 
-Master tool returning a complete 4D Score (0-100 per dimension plus overall) with one-sentence improvement tips.
+Reads cycles from a SQL database (PostgreSQL, SQLite). Coming in a future release.
 
-**Inputs:**
-- `description` (string, required): Task description
-- `delegation` (string, required): How the task is being delegated
-- `output` (string, optional): AI output to evaluate for discernment
+### nosql _(planned)_
 
-**Output:** Complete 4D profile with scores and improvement guidance
+Reads cycles from a NoSQL database (MongoDB). Coming in a future release.
 
-## Knowledge Base
+## Environment variables
 
-The server loads knowledge entries from the `knowledge/` directory at the workspace root. Knowledge files are YAML and must follow the schema defined in `@fluently/scorer`.
+| Variable | Default | Description |
+|---|---|---|
+| `FLUENTLY_CONNECTOR` | `github-public` | Which connector to use |
+| `FLUENTLY_GITHUB_REPO` | `faical-yannick-congo/fluently` | GitHub repo (`owner/repo`) |
+| `FLUENTLY_GITHUB_BRANCH` | `main` | Branch to read from |
+| `FLUENTLY_GITHUB_TOKEN` | _(none)_ | GitHub token — required for private repos and automated PRs |
+| `FLUENTLY_LOCAL_PATH` | `./knowledge` | Local knowledge directory (local connector only) |
 
-Each entry defines best practices and antipatterns for all four dimensions across different domains.
+## Why no scoring?
 
-## Architecture
+Numeric scores (delegation: 34/100) are biased by writing style and user maturity. Two people describing the same workflow in different vocabulary get different scores.
 
-- **Transport**: Stdio (primary) for local editor integration
-- **Schema Validation**: via Zod in `@fluently/scorer`
-- **Similarity Matching**: cosine similarity on keyword sets
-- **Knowledge Loading**: dynamic from `knowledge/` directory at startup
+This server does **retrieval** — it finds the most relevant cycles using keyword similarity and returns them for you to reason over. You assess fit in context. That's more accurate and adapts to the specifics of the situation rather than returning a false-precision number.
 
-## Development
+## Using GitHub MCP instead (community knowledge)
 
-To add new tools, edit `src/index.ts` and:
+If you prefer to skip the custom server and work directly with the public knowledge base via GitHub MCP, read `KNOWLEDGE.md` at the repo root. The raw `index.json` is fetchable without auth and contains all cycles.
 
-1. Define the Tool schema in a `*ToolDef` constant
-2. Register it in the `tools/list` handler
-3. Add the handler logic in the `tools/call` switch statement
-4. Rebuild and test
+The custom MCP server is the right choice when:
+- You need private knowledge that stays in your org
+- You want isolation from the community repo
+- You want structured tools (domain listing, dimension guidance, contribute flow)
+- You need the server to handle sync and refresh automatically
 
 ## License
 

packages/mcp-server/package.json

@@ -1,6 +1,6 @@
 {
   "name": "fluently-mcp-server",
-  "version": "0.1.2",
+  "version": "0.1.3",
   "description": "AI Fluency 4D Framework MCP server for scoring human-AI collaboration quality",
   "main": "dist/index.js",
   "types": "dist/index.d.ts",

packages/mcp-server/src/bin.ts

@@ -1,5 +1,3 @@
-#!/usr/bin/env node
-
 import { start } from "./index.js";
 
 start().catch((error) => {

packages/mcp-server/src/connectors/factory.ts

@@ -0,0 +1,22 @@
+import type { KnowledgeConnector } from './types.js';
+import { GitHubPublicConnector } from './github-public.js';
+import { GitHubPrivateConnector } from './github-private.js';
+import { LocalConnector } from './local.js';
+import { SqlConnector } from './sql.js';
+import { NoSqlConnector } from './nosql.js';
+
+export function createConnector(): KnowledgeConnector {
+  const type = (process.env.FLUENTLY_CONNECTOR ?? 'github-public').toLowerCase();
+  switch (type) {
+    case 'github-public':  return new GitHubPublicConnector();
+    case 'github-private': return new GitHubPrivateConnector();
+    case 'local':          return new LocalConnector();
+    case 'sql':            return new SqlConnector();
+    case 'nosql':          return new NoSqlConnector();
+    default:
+      throw new Error(
+        `Unknown connector "${type}". ` +
+        `Valid values: github-public (default), github-private, local, sql, nosql`
+      );
+  }
+}