Fluree MCP Server

A modern Node.js gateway that exposes FlureeDB functionality through the Model Context Protocol (MCP). It combines a rich set of MCP tools, structured prompts, and session-aware routing so any LLM-powered client (IDE, chat, or custom app) can query, mutate, and manage a Fluree ledger safely and interactively.

✨ Key Features

Related MCP server: kb-gateway

🗂️ Project Structure

src/
 ├─ config/            # Constant defaults & env helpers
 ├─ controllers/       # MCP server controller (session init, tool/prompt registration)
 ├─ routes/            # Express routes (`/api/v1/mcp`)
 ├─ tools/             # Individual MCP tools (each default export = { name, config, handler })
 ├─ prompts/           # Prompt templates mirrored one-to-one with tools
 └─ index.js           # Express bootstrap
.env.example           # Sample environment variables
README.md              # ← you are here

🚀 Quick Start

1. Clone & Install

   git clone https://github.com/UDAIBHAT/Fluree_MCP_Server.git
   cd fluree-mcp-server
   npm install
   cp .env.example .env   # adjust DB connection defaults if desired

2. Run

   npm start   # serves http://localhost:3000

3. Initialize a Session

   POST http://localhost:3000/api/v1/mcp
   Headers: { "Content-Type":"application/json" }
   Body:
   {
     "jsonrpc":"2.0",
     "id":1,
     "method":"initialize",
     "params":{
       "dbUrl":"Your_DBurl",
       "network":"Your_Network",
       "ledger":"Your_Ledger"
     }
   }

   The response includes mcp-session-id—add it to all subsequent requests.

4. Discover Tools & Prompts

   { "jsonrpc":"2.0", "id":2, "method":"prompts/list", "params":{} }

🖥️ IDE & Non-IDE Client Setup

IDE clients

Cursor, Windsurf,Google Gemini . RooCode can add the server definition to their settings. Two examples are shown below – one for Cursor and one for Windsurf:

CURSOR IDE

• Just insert this Patch of Json-code under the MCP-Section in the Cursor settings and you are good to go.....

{
  "mcpServers": {
    "Fluree_MCP_Server": {
      "url": "http://localhost:3000/api/v1/mcp",  
      "headers": {
        "dburl": "Your_DBurl",
        "network": "Your_Network",
        "ledger": "Your_Ledger"
      }
    }
  }
}

WINDSURF IDE

• Just insert this Patch of Json-code under the MCP-Section in the Windsurf Cascade settings and you are good to go.....

{
  "mcpServers": {
    "Fluree_MCP_Server": {
      "serverUrl": "http://localhost:3000/api/v1/mcp", 
      "headers": {
        "dbUrl": "Your_DBurl",
        "network": "Your_Network",
        "ledger": "Your_Ledger"
      }
    }
  }
}

GOOGLE GEMINI

• Use the following JSON patch in your Gemini .settings [ Currently Gemini doesnt support Streamable HTTP transport]

{
  "mcpServers": {
    "Fluree_MCP_Server": {
      "httpUrl": "http://localhost:3000/api/v1/mcp?dburl=<Your_DBurl>&network=<Your_Network>&ledger=<Your_Ledger>",
      "timeout": 30000,
      "trust": true
    }
  }
}

Non-IDE clients

Can simply POST to /api/v1/mcp (or /mcp) with a JSON body containing dbUrl, network, and ledger as shown in the Quick-Start initialization request.

🔧 Tools Overview

Each tool handler returns { content:[ {type:"text"|"json", text:string|object} ] }, ready for LLM streaming.

💬 Prompt Workflow

1. List → method:"prompts/list"

2. Get → method:"prompts/get", pass prompt name + arguments object

3. (Optional) Suggest → method:"completion/suggest" for auto-complete while filling arguments

Prompts use Mustache-style placeholders ({{argument}}) inside user messages to instruct the assistant to call the correct tool.

⚙️ Environment Variables

📑 API Collection

A ready-to-import Postman collection lives at docs/postman/Fluree_MCP.postman_collection.json (or generate it from the sample snippet in this README).

• You can also make a new collection with specified MCP endpoint ,postman supports the mcp endpoints so just inseret the server url then it will give you the whole list of tools.

• Just Import the collection and call the Initialize_req this will make Initialization_Connection to the MCP_Server and you can also change the params like dbUrl,network,ledger

• The mcp-session-id is dynamically stored in every request through Postman Post-Req Scripts

🛣️ Roadmap / Nice-to-Haves

• JWT authentication & role-based prompt permissions

• Rate limiting & CORS controls

• WebSocket support for real-time block watch

• Production observability: Prometheus exporter & Grafana dashboard

• Docker Compose bundle (Fluree + MCP + Grafana)

📜 License

MIT © UDAI BHAT