GraphMind

API-aware MCP server for Microsoft Graph — always fresh, never hallucinated.

GraphMind solves the core problem with AI + Microsoft Graph: LLMs have a training cutoff and will hallucinate endpoint paths for APIs released after training. GraphMind maintains a local, always-fresh index of the entire Graph API and uses a 3-tier funnel to find the correct endpoint for any natural language query.

Architecture

GraphMind sits between your AI client and Microsoft Graph. The AI never guesses endpoint paths — it searches a local, always-fresh index first, then executes the exact endpoint it found.

flowchart TD
    user["Natural language prompt"] --> client["AI client (Cursor / VS Code Copilot)"]
    client -->|"search_graph_api"| funnel["3-tier search funnel"]
    funnel --> schemas["Ranked endpoint schemas injected into AI context"]
    schemas --> pick["AI picks the exact endpoint"]
    pick -->|"call_graph_api"| writeCheck{"Write method?"}
    writeCheck -->|"GET"| exec["Execute against Microsoft Graph / Azure RM"]
    writeCheck -->|"POST / PATCH / PUT / DELETE"| preview["Return preview (confirmed=false)"]
    preview --> approve["User approves in chat"]
    approve -->|"confirmed=true"| exec
    exec --> result["Response (with pagination / aggregate)"]

The 3-tier search funnel

flowchart TD
    query["Natural language query"] --> tier1["Tier 1: Structural filter"]
    tier1 -->|"~45k endpoints to <= 500, ~1ms"| tier2["Tier 2: Cross-encoder rerank"]
    tier2 -->|"top 20, ~100ms, local 80MB model"| tier3["Tier 3: Full schemas injected into AI context"]
    tier3 --> pick["AI picks the exact endpoint"]

Search also applies domain hints (e.g. Cloud PC / snapshot queries auto-select api_version=beta and narrow tags). Write calls require user confirmation before execution.

Prerequisites

Python 3.11+ and git on your PATH. CI tests Python 3.11.
Internet access. The install downloads PyTorch via sentence-transformers (often 1 GB or more), the first run clones msgraph-metadata, and the first search downloads an ~80MB reranker model.
A Microsoft Entra tenant with an app registration (see docs/entra_setup.md)

Quick Start

git clone https://github.com/askaresh/graphmind.git
cd graphmind

python -m venv .venv

# Windows PowerShell
.venv\Scripts\Activate.ps1
# Windows cmd
.venv\Scripts\activate.bat
# macOS / Linux
source .venv/bin/activate

pip install -e ".[dev]"

# Configure — copy the example env, then fill in TENANT_ID, CLIENT_ID, AUTH_MODE
copy .env.example .env     # Windows (PowerShell / cmd)
cp .env.example .env       # macOS / Linux

# Verify (auto-clones msgraph-metadata on first run)
python -m graphmind.cli stats

# Start MCP server
python -m graphmind.cli serve

Use that activated virtual environment for every later command. After activation, graphmind stats works as well. If PowerShell blocks the activate script, call the venv interpreter directly: .venv\Scripts\python.exe -m graphmind.cli stats (macOS / Linux: .venv/bin/python -m graphmind.cli stats).

AUTH_MODE and credentials are read from .env. See docs/entra_setup.md for app registration and permissions.

The spec repo is cloned to ./msgraph-metadata automatically when missing. See docs/spec_lifecycle.md for the full lifecycle and recommended CI workflow.

What to expect on first run

Cold start (~4–6 min): the first tool call parses the full Graph OpenAPI spec (~45k endpoints) into an in-memory index. The MCP server responds to the handshake immediately and loads the index in the background; subsequent searches are instant until the process restarts. See docs/spec_lifecycle.md.
One-time model download (~80MB): the cross-encoder reranker downloads on the first search_graph_api call, then is cached locally.

Realistic time-to-first-query: GraphMind itself is clone-and-go in ~3 minutes. Because the one-time Entra app registration + admin consent and the cold-start parse are unavoidable, plan for ~10–15 minutes before your first live Graph call.

Cursor MCP setup

This repo includes .cursor/mcp.json. Credentials and AUTH_MODE stay in .env (not in MCP config):

{
  "mcpServers": {
    "graphmind": {
      "command": "python",
      "args": ["-m", "graphmind.mcp.server"],
      "cwd": "${workspaceFolder}",
      "env": {
        "SPEC_REPO_PATH": "./msgraph-metadata",
        "DEFAULT_API_VERSION": "v1.0",
        "RERANKER_TOP_K": "20"
      }
    }
  }
}

command must be the same interpreter you installed into. With the Quick Start venv, set it to ${workspaceFolder}/.venv/Scripts/python.exe on Windows, or ${workspaceFolder}/.venv/bin/python on macOS / Linux. A bare python only works when that python on PATH is the one that received pip install -e ".[dev]".

Keys in the MCP env block override the same keys in .env. Leave AUTH_MODE, TENANT_ID, CLIENT_ID, and secrets out of this block.

Enable GraphMind under Cursor Settings → MCP. The index loads in the background on the first tool call (~4–6 minutes cold; instant once warm). See docs/spec_lifecycle.md.

Agent behaviour for Graph queries is defined in .cursor/rules/graphmind-mcp.mdc.

VS Code (GitHub Copilot) MCP setup

This repo includes .vscode/mcp.json, which VS Code picks up automatically when you open the folder. It uses VS Code's MCP schema (servers + "type": "stdio"). Credentials and AUTH_MODE stay in .env (not in the MCP config):

{
  "servers": {
    "graphmind": {
      "type": "stdio",
      "command": "python",
      "args": ["-m", "graphmind.mcp.server"],
      "cwd": "${workspaceFolder}",
      "env": {
        "SPEC_REPO_PATH": "./msgraph-metadata",
        "DEFAULT_API_VERSION": "v1.0",
        "RERANKER_TOP_K": "20"
      }
    }
  }
}

Use the same venv interpreter for command as in the Cursor section above. MCP env values override .env.

Requires GitHub Copilot agent mode (Chat: Agent view). Open the Chat view, switch to Agent, then Start the graphmind server from the MCP tools picker. As with Cursor, the index loads in the background on the first tool call (~4–6 minutes cold).

Any other MCP-capable client works too. From the repo root, run python -m graphmind.mcp.server with the venv interpreter.

MCP tools

Always use this workflow for tenant / Graph questions:

search_graph_api — natural language query; returns ranked endpoint schemas
get_endpoint_schema — full parameters for a chosen path (optional)
call_graph_api — execute the call against Graph or Azure RM

Additional tool:

get_changelog — recently decommissioned endpoints from the spec diff pipeline

`call_graph_api` options

Parameter	Default	Purpose
`paginate`	`false`	Follow `@odata.nextLink` for large GET collections
`aggregate`	`true`	With `paginate`, return `{ total, sample }` instead of full JSON
`max_pages`	`50`	Page limit when paginating
`sample_size`	`10`	Rows in aggregate sample
`confirmed`	`false`	Required for writes — see below

Write confirmation: POST, PATCH, PUT, and DELETE calls return a preview on the first call (confirmed: false). Re-call with the same parameters and confirmed: true only after the user explicitly approves. Set GRAPHMIND_REQUIRE_WRITE_CONFIRMATION=false to skip (e.g. automation scripts).

404 handling: Failed calls suggest related endpoints from the local index when possible.

Example queries

Question	Approach
How many users?	search → `GET /users/$count` or `GET /users` with `paginate=true, aggregate=true`
List Cloud PCs	search → `GET /deviceManagement/virtualEndpoint/cloudPCs`
Cloud PC restore points	search (beta) → resolve Cloud PC id → `GET .../cloudPCs/{id}/retrieveSnapshots()`
Reboot a Cloud PC	search → POST `.../reboot` → preview → user confirms → `confirmed: true`

Many Windows 365 / Cloud PC APIs are beta-only. GraphMind auto-selects beta for Cloud PC and snapshot queries.

CLI

Command	Description
`graphmind serve`	Start MCP server
`graphmind bootstrap`	Clone msgraph-metadata (also runs automatically)
`graphmind refresh`	Pull latest spec + diff
`graphmind scheduler`	Run daily/weekly spec refresh scheduler
`graphmind stats`	Index statistics
`graphmind search "query"`	Terminal search (debug; no domain hints)

Helper scripts

Optional dev helpers under scripts/ bypass MCP (no write confirmation gate). See scripts/README.md for details.

Script	Purpose
`count_users.py`	Entra user count
`count_cloud_pcs.py` / `list_cloud_pcs.py`	Cloud PC inventory
`cloudpc_specs.py`	Cloud PC SKU details

Tenant-specific scripts belong in scripts/local/ (gitignored, not on GitHub).

Run from repo root, with the venv activated: python scripts/count_users.py. These scripts force AUTH_MODE=client_secret and need CLIENT_SECRET in .env. Interactive mode is enough for the MCP server and is not enough for these scripts.

Configuration

See .env.example for the full list. Key variables:

Variable	Default	Description
`DEFAULT_API_VERSION`	`v1.0`	Default API version for search and calls
`SPEC_AUTO_CLONE`	`true`	Auto-clone msgraph-metadata on first run
`STRUCTURAL_FILTER_CEILING`	`500`	Max candidates before reranking
`RERANKER_TOP_K`	`20`	Endpoints returned after rerank
`GRAPHMIND_READ_ONLY`	`false`	Block all write methods via MCP
`GRAPHMIND_REQUIRE_WRITE_CONFIRMATION`	`true`	Preview before POST/PATCH/PUT/DELETE
`GRAPHMIND_MAX_PAGES`	`50`	Default page limit for pagination
`GRAPHMIND_MAX_RESPONSE_CHARS`	`8000`	Truncate large MCP responses
`TOKEN_CACHE_PATH`	`./.graphmind_token_cache.json`	Persisted MSAL token cache

After changing Entra permissions, delete the token cache and retry.

Troubleshooting

Symptom	Likely cause	Fix
First tool call hangs for minutes	Cold start — parsing ~45k endpoints + one-time ~80MB model download	Expected on first run (~4-6 min). The MCP server is responsive; the index loads in the background. Subsequent calls are instant until restart.
`git ... not recognized` / spec never clones	`git` not on PATH, or no internet	Install git and ensure it's on PATH; GraphMind shells out to `git clone`. Or clone manually: `git clone https://github.com/microsoftgraph/msgraph-metadata ./msgraph-metadata`
`graphmind` is not recognized	The venv is not activated, or its `Scripts` folder is not on PATH	Activate `.venv`, or run `python -m graphmind.cli stats` with that venv's Python
`AADSTS50011` redirect URI mismatch	Interactive app registration is missing `http://localhost`	Add it under Authentication → Mobile and desktop applications (see docs/entra_setup.md)
`No OpenAPI specs found under ./msgraph-metadata`	Auto-clone disabled or wrong path	Set `SPEC_AUTO_CLONE=true`, or run `graphmind bootstrap`, or point `SPEC_REPO_PATH` at an existing clone
`KeyError: 'CLIENT_SECRET'` or auth fails at startup	`AUTH_MODE=client_secret`/`certificate` without the matching value	Set `CLIENT_SECRET` / `CERT_PATH`, or use `AUTH_MODE=interactive` for local dev (no secret needed)
`AADSTS65001` / consent or `403 Forbidden` on calls	App lacks the permission, or admin consent not granted	Add the permission in Entra and click Grant admin consent (see docs/entra_setup.md). Then delete `.graphmind_token_cache.json` and retry
Calls still 403 after adding permissions	Stale cached token without new claims	Delete `.graphmind_token_cache.json` so MSAL acquires a fresh token
`404 Not Found` on a beta path	Endpoint is v1.0-only, or path is wrong	Retry with `api_version='v1.0'`, or run `search_graph_api` again — 404s suggest related endpoints from the local index
`pip install` fails on `numpy`/`torch`	Resolver conflict or unsupported Python	Use Python 3.11+ in a clean virtualenv. `numpy` is pinned `<2` for `sentence-transformers` compatibility
`Server` has no attribute `list_tools`	MCP 2.x was installed	Reinstall from this repo. GraphMind requires MCP 1.x (`mcp>=1.27.1,<2`)
`search_graph_api` returns no results	Filters too narrow	Broaden the query, drop `tags`/`method`, or set `api_version='both'`
MCP server not appearing in the client	Wrong `cwd` or command	Launch from the repo root (`cwd`) so `./msgraph-metadata` and `.env` resolve. Set `command` to the venv interpreter, then verify `python -m graphmind.mcp.server` runs with that same Python

For a quick non-MCP sanity check, run python -m graphmind.cli stats (loads the index) and python -m graphmind.cli search "list all users" (exercises the funnel) from the repo root.

GitHub Actions

.github/workflows/test.yml — runs on push/PR: compileall + pytest
.github/workflows/refresh.yml — daily at 02:00 AEST, pulls latest msgraph-metadata, diffs against the stored manifest, and commits changes. No auth secrets required for the spec refresh job.

Development

From the activated Quick Start virtual environment:

pip install -e ".[dev]"
python -m pytest tests/ -v
python -m compileall graphmind

Contributing & community

Contributions are welcome. Please read:

CONTRIBUTING.md — dev setup, checks, branch/PR conventions
CODE_OF_CONDUCT.md — community expectations
SECURITY.md — how to report vulnerabilities (do not open a public issue)
CHANGELOG.md — notable changes per release

Use the issue templates for bug reports and feature requests, and the pull request template when opening a PR.

License

GraphMind is released under the MIT License.

Navigation Menu

Repository navigation

About

Repository files navigation

GraphMind

Architecture

The 3-tier search funnel

Prerequisites

Quick Start

What to expect on first run

Cursor MCP setup

VS Code (GitHub Copilot) MCP setup

MCP tools

`call_graph_api` options

Example queries

CLI

Helper scripts

Configuration

Troubleshooting

GitHub Actions

Development

Contributing & community

License

About

Releases

Packages

Contributors

Languages

Name		Name	Last commit message	Last commit date
.cursor		.cursor
.github		.github
.vscode		.vscode
docs		docs
graphmind		graphmind
scripts		scripts
tests		tests
.env.example		.env.example
.gitignore		.gitignore
AGENTS.md		AGENTS.md
CHANGELOG.md		CHANGELOG.md
CODE_OF_CONDUCT.md		CODE_OF_CONDUCT.md
CONTRIBUTING.md		CONTRIBUTING.md
LICENSE		LICENSE
README.md		README.md
SECURITY.md		SECURITY.md
graphmind_manifest.json		graphmind_manifest.json
graphmind_promotion_log.json		graphmind_promotion_log.json
pyproject.toml		pyproject.toml

Latest commit

History

Folders and files

Repository files navigation

GraphMind

Architecture

The 3-tier search funnel

Prerequisites

Quick Start

What to expect on first run

Cursor MCP setup

VS Code (GitHub Copilot) MCP setup

MCP tools

call_graph_api options

Example queries

CLI

Helper scripts

Configuration

Troubleshooting

GitHub Actions

Development

Contributing & community

License

About

Topics

Resources

Code of conduct

Contributing

Security policy

Stars

Watchers

Forks

Releases

Packages

Contributors

Languages

`call_graph_api` options