Brainograph.KnowledgeGraph.McpServer 1.0.2

Brainograph.KnowledgeGraph.McpServer (graph-mcp)

The Brainograph knowledge-graph MCP server, distributed as a .NET tool. It serves the same 20 graph tools over stdio that bg-knowledgegraph's API host serves over streamable-HTTP at /mcp — one tool implementation, two transports.

Which transport should I use?

Prefer HTTP. The canonical, decoupled path is the API host's /mcp endpoint: the consuming service needs no database handle and no build of this repo.

This stdio tool is the offline / fallback transport. It runs the query layer in-process, so it needs its own connection to knowledge_db — meaning anything using it takes a direct dependency on another service's database. That is why the fallback entry in bg-aiagent's mcpservers.json ships enabled: false.

Install

As a local tool (recommended — pins the version in .config/dotnet-tools.json):

dotnet new tool-manifest     # only if the repo has no .config/dotnet-tools.json yet
dotnet tool install Brainograph.KnowledgeGraph.McpServer --version 1.0.2
dotnet tool restore          # on a fresh clone

The package is unlisted on nuget.org by org policy, which does not affect restore by exact version.

Run

dotnet tool run graph-mcp serve        # MCP server over stdio
dotnet tool run graph-mcp overview
dotnet tool run graph-mcp resolve "Տիգրան Մեծ"
dotnet graph-mcp --help                # full verb list; needs no database

Use dotnet graph-mcp … (not dotnet tool run graph-mcp …) when passing --help: dotnet tool run treats a leading --help as its own.

Every one of the 20 tool names below is also a CLI verb, matched case-insensitively — so findArticles and findarticles both work. stdout is reserved for the MCP protocol; logs go to stderr.

Configuration

One required setting, resolved in this order:

1. ConnectionStrings__KnowledgeGraph
2. KNOWLEDGE_DB_URL
3. a .env / .env.local file in the working directory (real environment variables win)

Either key name works in a .env file too — __ is treated as a section separator exactly as it is for environment variables.

It fails fast with an actionable message naming all three if none is set. Embedding-backed tools (search, passages, gather, imageSearch) additionally need EMBED_API_KEY or OPENROUTER_API_KEY; every other tool works without them.

Requirements

.NET 10, and the ASP.NET Core shared framework — not just the .NET runtime. The graph layer pulls it in transitively through the platform shared kernel, so a runtime-only machine cannot launch this tool. Anywhere the SDK is installed, it is already present.

Registering with an MCP host

{
  "name": "graph-stdio",
  "transport": "stdio",
  "command": "dotnet",
  "args": ["tool", "run", "graph-mcp", "serve"],
  "env": { "KNOWLEDGE_DB_URL": "Host=…;Database=knowledge_db;Username=…;Password=…" },
  "enabled": false
}

Tool names are contract and are pinned with [McpServerTool(Name = "…")]: resolve · entity · neighbors · subgraph · path · facts · imagesFor · imageSearch · articleImages · search · articles · article · articleText · articleGraph · passages · gather · browse · timeline · findArticles · overview.

Start with gather for substantive questions — it returns semantic evidence and graph context in one call.

Payloads are snake_case and un-enveloped; every tool's response shape is documented in docs/CONTRACT-knowledgegraph.md in the bg-knowledgegraph repository (not shipped in this package). An unknown id returns null rather than an error, for entity, article, articleText, articleGraph and path.