knowledge-gateway
A single MCP server that gives agents (Claude Code, Codex, Cursor, Copilot, Antigravity) three capabilities over one connection:
- Vault - read, search, and edit a git-backed Markdown/Obsidian vault (no Obsidian GUI), git as the source of truth.
- Code graph - build and query a knowledge graph of a repo: definitions, imports and calls across ~30 languages (TypeScript/JavaScript, Go, Rust, Java, C#, C/C++, Ruby, PHP, Kotlin, Swift, Terraform/HCL and more) plus Python, and dedicated passes for the files a grammar cannot read as structure: Ansible (roles, playbooks, inventories, templates), Microsoft Fabric, Azure Bicep, Docker and compose, Kubernetes manifests and Helm charts, GitHub Actions, Appsmith apps, and dependency manifests (pyproject, requirements, package.json, .NET projects, Galaxy). Names and references only, never values. AST-only, local, no LLM.
- Convert (
[convert]) - turn PDF / Office / image / HTML files into Markdown.
Install knowledge-gateway[graph] - the vault tools and the code graph. [convert] is separate
only because its PDF/Office parsers pull a materially larger, native-extension dependency tree.
The vault layer exists because the Obsidian Local REST API plugin serves only the one vault open in a running desktop instance, writes without a lock (silent lost updates), needs a token in every client, and treats git as secondary. This gateway operates on the files directly, with git as the system of record - and serves the graph and convert tools over the same connection: one server, no new servers to wire.
Architecture
flowchart LR
subgraph clients [Agents]
A1[Claude Code]
A2[Codex]
A3[Copilot - VS Code]
A4[Cursor]
A5[Antigravity - Gemini]
end
A1 --- M(( MCP ))
A2 --- M
A3 --- M
A4 --- M
A5 --- M
M -->|stdio, per repo, no auth| L[Local gateway]
M -->|HTTP + bearer + ACL| S[Shared gateway]
L --> V[/Vault: Markdown files/]
S --> V
V <-->|atomic write + scoped commit| G[(git)]
Both modes run the same tool implementation over the same path guards; they differ in transport, authentication/ACL, vault loading, and error masking.
Two ways to run
| Local mode (per repo) | Shared server (team) | |
|---|---|---|
| Use when | a repo wants its own vault for its agents | many people/vaults behind one always-on endpoint |
| Transport | stdio subprocess (launched by .mcp.json) |
HTTP |
| Secrets / tokens | none - nothing to generate | per-user bearer tokens (admin-generated) |
| Trust boundary | local filesystem access you already have | per-user bearer token + per-vault ACL |
| Obsidian needed | no | no |
Most repos want Local mode. The shared server is for a central, always-on team gateway.
Distribution - PyPI ("update once")
The gateway ships as a PyPI package, so a release reaches every consumer and server without re-pinning anything by hand.
flowchart LR
PR[merge version bump PR to main] --> CI[green ci on main]
CI --> REL["release.yml<br/>publish PyPI + tag vX.Y.Z"]
REL --> C["Consumers<br/>uvx --refresh knowledge-gateway<br/>(updates next session)"]
REL --> S["Servers<br/>daily uv tool reinstall<br/>(restart if the version moved)"]
- Consumers run
uvx --refresh --from 'knowledge-gateway[graph]' knowledge-gateway-> the latest release is resolved on every launch, so a new release auto-propagates the next time an agent starts. No per-repo re-pin. - Servers (long-running) run
uv tool install 'knowledge-gateway[graph,convert]'plus a daily job that reinstalls + restarts only when the published version actually moves. - Every release is also an immutable
vX.Y.Zgit tag - pin==X.Y.Zwhen you need a frozen, auditable version.
Branches
| Ref | What it is |
|---|---|
main |
development and the latest release. Every release is cut from a green ci here |
vX.Y.Z |
immutable tag per release, for a frozen or auditable pin |
The stable compatibility branch is retired with v0.12.0. Existing @stable requirements
must migrate to PyPI, preserving their extras and server arguments:
uvx --refresh --from 'knowledge-gateway[graph]' knowledge-gateway --local.
Persistent servers use uv tool install 'knowledge-gateway[graph,convert]' and their configured
updater. Pin ==X.Y.Z for a fixed package version. Running development main does not track
published releases.
Quickstart - local mode (zero secrets)
Add this to the repo's .mcp.json at the repo root:
{
"mcpServers": {
"wiki": {
"command": "uvx",
"args": ["--refresh", "--from", "knowledge-gateway[graph]",
"knowledge-gateway", "--local"]
}
}
}
--localauto-detects the vault in the cwd, in order: the cwd itself if it has.obsidian/, then./wiki, then a single*-obsidian-vault/, then a single child dir with.obsidian/(ambiguous matches error). Pass--vault ./<dir>to be explicit.--refreshre-resolves the latest release each launch, so releases auto-apply (adds ~1-2s to start).- Commits are scoped to the vault's git subdir and attributed to your own
git config user.name/email. No token: the trust boundary is local filesystem access.
Open the repo in your agent, approve the wiki server once, done.
Tools
| Tool | |
|---|---|
list_vaults |
vaults reachable here |
list_notes |
Markdown paths in a vault |
read_note |
raw note content |
list_attachments / read_attachment |
list / read binary attachments (image -> inline Image, else an embedded resource carrying the file's real media type) |
list_canvases / read_canvas / write_canvas |
list / read / write Obsidian Canvas (nodes, groups, colors) |
search |
ripgrep literal/regex full-text |
backlinks |
notes that [[wikilink]] to a note |
list_tags |
inline #tags with counts |
query_notes |
find notes by frontmatter type / tag (headless Dataview-lite) |
write_note |
atomic write (+ optional commit) |
patch_note |
insert after a heading or at top/bottom, no full rewrite (+ commit) |
patch_frontmatter |
update YAML frontmatter keys, body intact (+ commit) |
delete_note |
delete a note (+ optional commit) |
rename_note |
rename/move + rewrite inbound flat [[wikilinks]] when the name changes (+ optional commit) |
git_status / git_commit |
pending changes / commit (subdir-scoped, attributed) |
list_graphs / graph_query / graph_neighbors / god_nodes / graph_shortest_path / graph_stats |
query a built code graph. list_graphs and graph_stats also report where each snapshot came from - the revision, the build time, and whether the file still matches its manifest |
graph_build |
build a code graph from a source tree into .graph/<name>.json (local mode only) |
convert_to_markdown |
convert a document in the vault to Markdown (needs [convert]). Allowlisted types only - PDF, Office, image, HTML, CSV, EPUB, Outlook, audio/video - so a token that may read notes cannot read an arbitrary file that happens to sit in a vault; anything else is not_convertible |
Note writes are atomic (temp file + rename) and use safe_note_path. Attachments, canvases,
conversion inputs and graph files use their own type-specific containment guards. Together they
block traversal, symlink escape and access outside the configured vault.
Agent skills
The repository includes a validated, provider-neutral Agent Skills pack under .agents/skills/,
a real directory that Codex, Gemini CLI, GitHub Copilot and Cursor discover natively. Claude Code
reads the same files through the repository plugin in .claude-plugin/. Agent instructions follow
the same rule: AGENTS.md is canonical, and CLAUDE.md / GEMINI.md are regular files that
import it. The repository tracks no symlinks, so a Windows checkout without Developer Mode (or any
core.symlinks=false checkout) gets the full instructions and skills.
Consumer repositories can instead own copies in their documented project-level directory.
The pack covers:
gateway-setupandgateway-operationsfor configuration, verification, operation and release;code-graph-build,code-graph-exploreandcode-impactfor architecture discovery and blast-radius analysis;wiki-query,wiki-curate,wiki-ingest,wiki-lint, andwiki-foldfor durable knowledge;canvasandobsidian-markdownfor Obsidian-native authoring;document-convertfor reviewed PDF and Office conversion; andcordis-composabilityfor reversible effects and declared dependencies.
Skills add repeatable procedures, not privileges. Server-side ACLs, path guards, hooks and CI remain
the enforcement layer. The machine-readable inventory is .agents/skills/manifest.json; CI
validates that every skill is registered and references only real gateway tools, that the plugin
manifest points at the pack at the package version, and that git tracks no symlinks. The source
distribution keeps shipping the pack under skills/.
Claude Code quickstart. Claude Code discovers project-level skills only in .claude/skills,
so it loads this pack from the plugin manifest once you opt in; skills then appear as
/knowledge-gateway:<skill>. From the repository root (recommended; the plugin is read in
place, so skill edits apply immediately):
claude --plugin-dir .
A persistent install is possible when you keep exactly one clone per OS user:
claude plugin marketplace add ./ --scope local
claude plugin install knowledge-gateway@knowledge-gateway --scope local
The marketplace registration is per OS user, not per clone: running these commands in a second
clone re-points the plugin of every clone at that second clone. The install records the clone's
absolute path in ~/.claude/plugins/ and the git-ignored .claude/settings.local.json, and copies
the whole working tree (untracked files included) into ~/.claude/plugins/cache/, so do not keep
secrets in the checkout when you install. Do not use --scope project: it rewrites the committed
.claude/settings.json with an absolute path.
Copy selected skills into the destination listed in the sourced compatibility table:
mkdir -p ../consumer/.agents/skills
cp -R .agents/skills/wiki-query .agents/skills/wiki-curate ../consumer/.agents/skills/
Copy on a branch, do not overwrite an existing same-name skill blindly, and review the consumer diff. The copied files are then owned and versioned by the consumer repository.
See docs/agent-skills.md for the compatibility matrix, required extras,
workflow harness, maintenance rules and security boundaries.
For the complete pack, run local mode with every capability, conversion included:
{
"mcpServers": {
"wiki": {
"command": "uvx",
"args": [
"--refresh",
"--from",
"knowledge-gateway[all]",
"knowledge-gateway",
"--local"
]
}
}
}
The dependency-free core quickstart above remains the preferred setup when only vault operations are needed.
Code graph and conversion
Install profiles. The core vault tools need no third-party parser at all; the code graph ships
in the recommended [graph] install, and conversion is separate because its PDF/Office parsers
pull a materially larger, native-extension dependency tree:
| Install | What you get |
|---|---|
[graph] |
the code graph and its query tools, over every supported language: a tree-sitter pass across ~30 grammars (JS/TS/TSX, Go, Rust, Java, C#, C/C++, Ruby, PHP, bash, PowerShell, Terraform/HCL, Lua, Kotlin, Swift, Scala, R, Perl, Elixir, Clojure, Dart, SQL, Groovy, Julia, Solidity, Haskell, OCaml) plus Python via the stdlib ast, plus the dedicated passes below (Ansible, Microsoft Fabric, Azure Bicep, Docker, Kubernetes/Helm, GitHub Actions, Appsmith, dependency manifests, Jenkins, AWS Elastic Beanstalk, HTTP request files, ASP.NET Core endpoints) |
[graph-slim] |
the same tools with only the dependency-free extractors: Python and every dedicated pass below (they need the stdlib and PyYAML, never tree-sitter). Pick this only when the parser pack is not worth its size; without it, bash, PowerShell, C# and the other grammars get no definitions, though a dedicated pass still emits the module:<rel> node of a script it references |
[graph-all] |
alias of [graph], kept so older pins keep resolving |
[convert] |
attachment -> Markdown via MarkItDown; opt-in PDF and Office parsers add a materially larger dependency tree, including native-extension packages |
[all] |
[graph] + [convert] in one pin - the whole toolset, and the string to use when a config should not drift apart from what the CLI has installed |
Microsoft Fabric
A git-integrated Fabric workspace is mostly JSON and TMDL. Parsing that as JSON would emit a node per key and answer nothing, so there is a dedicated pass that reads the shapes Fabric writes:
| Read | Emitted |
|---|---|
<Name>.<Type>/.platform |
fabric:<Type>:<displayName> - identity from the descriptor, including logicalId |
<Name>.DataPipeline/pipeline-content.json |
one node per activity (nested ForEach/If included), depends_on for order, invokes for what each one runs |
<Name>.SemanticModel/definition/**/*.tmdl |
tables and the measures under them |
<Name>.Report/definition.pbir |
reads_model -> the semantic model |
<Name>.Notebook/notebook-content.py |
implemented_by -> the module: node the Python pass produced |
That last edge is the point: it joins the artifact map to the code graph, so "what breaks if I change this notebook" is one query rather than two graphs and a guess. References resolve by logical id where Fabric writes one and by display name where it does not - both occur in real exports.
Deliberately absent: notebook -> lakehouse table lineage. That needs heuristics over Spark code rather than structure, and a wrong guess there is an edge that looks authoritative and is not.
Infrastructure, CI and app passes
The same idea covers the rest of a deployment repository. Each of these is a repo-level pass
(stdlib + PyYAML only, so it runs under [graph-slim] too), and they share one contract:
- Names, never values. No variable, parameter or environment value, no default, no
Secret
data, no datasource URL, header or body, no inventory variable reaches the graph - only the names and keys that give it structure. Each pass has a test that plants a unique secret-looking value everywhere a value can sit and asserts it appears nowhere in the output. - One id per file. When a pass references a file another pass owns, it uses that pass's id
(
module:<rel>for code and scripts,playbook:<rel>,dockerfile:<rel>,manifest:<rel>,project:<rel>), so a CI job, the script it runs and the image that script builds are one path through the graph, not three islands. - Structure only. No template evaluation (Helm, Jinja, Bicep,
${{ }}), no network, no registry lookup, no subprocess. Directories are pruned with the rule above, walks are sorted, a symlink is never followed out of the root, files over 2 MiB are skipped, and a malformed or unreadable file is skipped rather than failing the build. Heuristic edges areINFERRED.
graph_stats reports which passes ran in passes, with the number of nodes each one emitted
(-1 when a pass raised on input it did not foresee: its output is left out and the build
goes on). The graph keeps one edge per pair of nodes; when a pair is related in more than one
way (a stage that copies a script and then runs it), the edge lists every relation in
relations, and graph_neighbors returns that list too.
A few joins need both ends at once, and no single pass sees both. These run once, after every
fragment is merged and before communities are computed, as post-merge links: they read node
attributes only, add INFERRED edges between nodes that already exist (never a node), and are
deterministic. graph_stats reports them in links, as the number of node pairs each one
joined (-1 when it raised: its edges are left out, the build goes on). See calls_api under
ASP.NET Core below.
Ansible - extended beyond roles:
| Read | Emitted |
|---|---|
any *.yml/*.yaml list whose plays carry hosts or import_playbook |
playbook:<rel>, imports_playbook, targets -> the inventory group or host a play names (INFERRED when no inventory here defines it) |
template / copy tasks |
renders_template -> template:<rel>, copies_file -> file:<rel> (or the module:<rel> of copied code), resolved the way Ansible searches |
| INI and YAML inventories | invgroup:<name>, invhost:<name>, member_of, child_of |
group_vars/ and host_vars/ |
vars:<rel> -> configures the group or host; the files are never parsed |
Absent: every variable name and value, [x:vars], inline host variables, copy: content:,
vault payloads (a !vault tag parses to nothing), dynamic inventory and host-pattern evaluation.
Azure Bicep:
| Read | Emitted |
|---|---|
*.bicep |
bicep:<rel>, and per declaration bicepparam:, bicepoutput:, bicepresource: (nested parent::child included, with resource type and API version), bicepmodule:; uses_module -> bicep:<rel> or extbicep:<registry ref>, imports, child_of, depends_on (EXTRACTED from dependsOn, INFERRED from symbolic references) |
*.bicepparam |
parameterizes -> its using template, extends, sets_param -> the template param it assigns (the name, never the value) |
getSecret(...), @Microsoft.KeyVault(...), secret URLs |
reads_secret -> kvsecret:<vault>/<secret> by name |
az deployment ... create|what-if|validate, az stack, New-/Test-Az*Deployment in scripts |
deploys from the script's module:<rel> to the template and parameter file, with operations |
Absent: param defaults, .bicepparam assignments, var bodies, property values, descriptions,
tags; no compilation and no registry lookup.
Docker and compose:
| Read | Emitted |
|---|---|
Dockerfile, Containerfile, *.Dockerfile, Dockerfile.* |
dockerfile:<rel>, dockerstage:<rel>#<stage>, based_on -> extimage:<name[:tag]> or a prior stage, copies / copies_from, runs -> the copied file an ENTRYPOINT/CMD/RUN executes |
compose*.y[a]ml, docker-compose*.y[a]ml |
compose:<rel>, composeservice:<rel>#<service>, uses_image, builds_from, targets_stage, depends_on, mounts (bind mounts), uses_env_file |
docker|podman build/push in scripts |
builds (INFERRED: the build context is a guess) and pushes |
Absent: ENV/ARG/--build-arg/environment values (names only), env_file contents (never
read), labels, RUN text, secrets/configs, remote build contexts; ${VAR} is never expanded.
Kubernetes and Helm:
| Read | Emitted |
|---|---|
Chart.yaml, Chart.lock, requirements.yaml |
helmchart:<dir>, depends_on -> a local chart or exthelmchart:<repo>/<name> (credentials stripped from repository URLs) |
chart templates/** (scanned tolerantly, never rendered) |
helmres:<chart>/<Kind>/<name>, renders, reads_value -> helmvalue:<chart>/<top-level key> |
values.yaml and environment overlays |
helmvalues:<file>, default_values_of, overrides (INFERRED from name and location), defines_value |
helm install|upgrade in scripts |
helmrelease:<ns>/<name>, deploys from the script's module:<rel>, installs, uses_values (with -f order) |
plain manifests and kustomization.yaml |
k8sres:<ns>/<Kind>/<name>, kustomization:<file>, includes, generates, selects (INFERRED by labels), routes_to, uses_secret / uses_configmap / uses_service_account / uses_pvc, binds_role, binds_subject |
Absent: Secret and ConfigMap data, env values, --set arguments, values-file values (top-level
key names only), kustomize literals and valuesInline, labels; no Helm rendering, no remote
bases. A YAML list (an Ansible playbook) is never read as a manifest.
GitHub Actions (read from .github/ directly, although the prune rule hides it; naming
.github in --exclude turns the pass off):
| Read | Emitted |
|---|---|
.github/workflows/*.y[a]ml |
ghworkflow:<rel>, ghjob:<rel>#<job>, contains, depends_on (needs), calls_workflow -> ghworkflow: or extworkflow: |
uses: |
uses_action -> ghaction:<dir> (local) or extaction:<owner>/<repo> (the ref is an edge attribute) |
${{ secrets.X }}, ${{ vars.X }} |
uses_secret -> ghsecret:<NAME>, uses_var -> ghvar:<NAME> |
run: shell lines |
runs_script (INFERRED) -> the module:, playbook: or dockerfile: node of the file it runs, file:<rel> otherwise |
Absent: every env:, with:, matrix, input-default and environment-URL value, container and
service images; no expression is evaluated and no remote action is fetched.
Appsmith (a git-synced export, found by its metadata.json marker):
| Read | Emitted |
|---|---|
application.json, pages/<page>/ |
appsmith:<app>, appsmithpage:<app>/<page>, contains, navigates_to |
widgets/**.json |
appsmithwidget:<app>/<page>/<widget> nested by parent (layout canvases collapsed) |
queries/<q>/ and datasources/ |
appsmithquery: (plugin, HTTP method, the shape of the URL path: bindings and every segment that is not a plain word become {}, since tokens are often carried in the path; route_shape is that shape in the canonical form the HTTP and ASP.NET passes share, one leading / and no trailing one), appsmithdatasource: (plugin only), uses_datasource |
{{ }} bindings and jsobjects/ |
triggers (<Query>.run(), <JS>.<fn>()), reads (<Query>.data), references (INFERRED), implemented_by -> the .js file's module:<rel> |
Absent: datasource configuration (URLs, credentials, auth), headers, bodies, query parameters, hosts and query strings, widget text and defaults, JS code.
Dependency manifests:
| Read | Emitted |
|---|---|
pyproject.toml, requirements*.txt, package.json, Galaxy requirements.y[a]ml |
manifest:<rel>, depends_on -> extpackage:<pypi|npm|galaxy>:<name> (version specifier and scope as attributes), includes / constrained_by for -r / -c |
*.csproj (any *proj), *.sln, *.slnx |
project:<rel>, solution:<rel>, depends_on -> extpackage:nuget:<id>, references_project, contains -> the module:<rel> of each .cs file (INFERRED from the SDK glob) |
Absent: index URLs and other pip options, direct-reference and git URLs (reduced to the package
name plus an origin), MSBuild property values such as UserSecretsId, lock files; nothing is
resolved against a registry. A Galaxy requirement provides (INFERRED) the role:<name> a
playbook references by that name (a collection ns.coll provides ns.coll.<role>), so a role
that is installed rather than vendored is typed instead of dangling.
Jenkins (Jenkinsfile, Jenkinsfile.*, *.jenkinsfile, *.groovy and files named for
Jenkins other than documentation such as .md / .rst / .html, kept only when they hold a
pipeline {} or node {} block; a linear Groovy tokenizer, never evaluated):
| Read | Emitted |
|---|---|
declarative pipeline { stages { ... } } and scripted node { stage(...) }, shared-library def call() |
jenkinspipeline:<rel>, jenkinsstage:<rel>#<stage path>, contains (nested and parallel stages), depends_on -> the previous stage in sequence (EXTRACTED declarative, INFERRED scripted) |
credentials('id'), withCredentials([...]), registryCredentialsId |
uses_credential -> jenkinscredential:<id> (the id; via names the binding or step, variable the environment name a credentials('id') fills) |
agent { docker / dockerfile }, docker.image().inside, docker build/push, docker.build() |
uses_image / pushes -> extimage:, builds -> dockerfile:<rel> |
sh / bat / powershell / load steps |
runs_script (INFERRED) -> the module:<rel> / file:<rel> it runs, resolved through dir() / cd |
helm upgrade|install, eb deploy, aws elasticbeanstalk update-/create-environment, dotnet eb deploy-environment, dotnet build|publish|test |
deploys -> helmrelease:<ns>/<name> (the k8s pass's id) or beanstalkenv:<app>/<env> (the Beanstalk pass's id and name rules, with beanstalkapp:<app> has_environment when the application is named), installs -> a local helmchart:, builds / tests (dotnet test) -> project:<rel> |
Absent: every environment and parameter value (names only), credential secrets, --set and
option values, URLs, hosts, headers and bodies (httpRequest is not read), shell text, build job: triggers, shared-library fetching.
AWS Elastic Beanstalk (read in place from each directory: .ebextensions, .platform and
.elasticbeanstalk stay pruned from the walk, and naming one in --exclude turns that part off;
bin/ and obj/ beside a .NET project are build output and pruned too, unless --included):
| Read | Emitted |
|---|---|
.ebextensions/*.config (YAML or JSON) |
beanstalkbundle:<dir>, beanstalkconfig:<rel> (option namespaces and <ns>/<option> names, environment-variable names, package / service names, command names), beanstalkresource:<rel>#<LogicalId>, defines_resource, depends_on, runs_script (INFERRED) -> the bundle script a command invokes |
.elasticbeanstalk/config.yml, aws-<tool>-tools-defaults*.json |
beanstalkcli:, awsdeploydefaults:, beanstalkapp:<app>, beanstalkenv:<app>/<env>, targets, deploys_to, configures -> project:<rel> |
.platform/hooks|confighooks/<phase>/*, Procfile, Dockerrun.aws.json |
runs (hook, phase), beanstalkprocess:, dockerrun:, dockerruncontainer:, uses_image -> extimage:, links |
Absent: every option_settings value, command text, env / cwd / test, file contents and
sources, package versions and URLs, resource properties and outputs, Dockerrun auth, volumes and
environment values, Procfile commands, and every defaults-file value except the application,
environment, solution stack, project path and a plain region code.
HTTP request files (*.http, *.rest: VS Code REST Client, JetBrains HTTP Client, Visual
Studio):
| Read | Emitted |
|---|---|
request blocks (###), # @name, METHOD URL |
httpfile:<rel> (file-variable names), httprequest:<rel>#<name or position> with method, route_shape, header names, uses_auth, variable and prompt names, has_request |
{{name.response...}}, < ./body.json, > ./check.js, import / run |
uses_response, body_from / runs -> the file's module:<rel> / file:<rel>, imports |
route_shape follows the Appsmith rule: the query string and fragment are cut first, then
scheme, userinfo, host and port (the first segment of a scheme-less URL is its host) and a
leading {{base}} binding are dropped, and a binding inside the path becomes {}. A leading
file variable that holds a URL (@base = https://h/api/v2) is substituted only as one {} per
path segment it contributes (GET {{base}}/items -> /{}/{}/items), so no part of its value
reaches the graph. Absent: every file-variable, header and body value, auth schemes, query
strings and parameter names, comments and ### titles, inline {% %} scripts; environment
files are never read.
ASP.NET Core (*.cs, a linear C# tokenizer; no compiler, bin/ and obj/ pruned):
| Read | Emitted |
|---|---|
controllers ([ApiController], *Controller, ControllerBase) with [Route], [Http*], [AcceptVerbs], [Area], [ApiVersion] |
endpoint:<METHOD> <route shape> (kind, controller, action, auth required|anonymous), handled_by -> the .cs file's module:<rel> |
minimal APIs: MapGet / MapPost / ... / MapMethods / Map (not the app.Map("/x", b => b.Run(...)) middleware branch), MapGroup prefixes, RequireAuthorization / AllowAnonymous |
the same endpoint: nodes; optional_segments counts trailing {id?} / {id=1} / {*rest} segments a caller may omit |
the enclosing *.csproj (located, not parsed) |
aspnetapp:<project dir>, exposes, defined_by -> project:<rel> |
Post-merge link calls_api (INFERRED): an appsmithquery: or httprequest: node calls the
endpoint: with the same method (or ANY) whose route shape it matches; the match attribute
says how - exact, pattern (a {} on either side stands for one segment) or suffix (the
client path ends the endpoint route, its leading base-URL {} segments dropped). At least one
literal segment must match, literals compare case-insensitively as ASP.NET routing does, and a
client with more than four equally good candidates gets no edge. Clients and endpoints join only
inside one graph, so a UI and the API it calls built as separate graphs do not link.
Absent: [Authorize] policy and role names, constant values, appsettings*.json, header names
and values, bodies, conventional routes (MapControllerRoute), actions without a route or verb
attribute, inherited actions, interpolated templates, Razor Pages, gRPC, SignalR, Functions.
Build a graph (AST-only - local, no network, no LLM) where the code lives:
knowledge-gateway-graph /path/to/code-repo -o /path/to/vault/.graph/myrepo.json
# in a local-mode session the graph_build tool does the same, writing .graph/<name>.json
Both write a <name>.meta.yaml sidecar beside the snapshot: the source revision, the build
time and the snapshot's SHA-256. A graph is a snapshot and cannot refuse to be stale, so that
provenance travels with the answer - list_graphs carries each snapshot's revision and build
time, and graph_stats adds snapshot_matches, false when the snapshot changed after its
manifest was written. The sidecar holds no absolute path, only the source directory's basename.
Hidden directories (.git, .next, .venv, caches, ...) and common build/vendor output
(node_modules, dist, build, target, vendor, ...) are always skipped.
--exclude <name> ... adds directory names to skip; --include <name> ... force-keeps
names the rule would skip (e.g. .github, a first-party vendor/). Matching is by
directory basename, not path or glob. Same exclude/include on the graph_build tool.
Query it over MCP with graph_query / graph_neighbors / god_nodes /
graph_shortest_path / graph_stats. The graph captures functions, classes, imports and calls
in every supported language.
Ansible gets its own extractor rather than a grammar, because a playbook is YAML: a parser sees
mappings and lists, not structure. That pass reads the semantics - roles, tasks, handlers,
include_role / import_tasks / notify, task -> filter plugin edges, and the playbook,
inventory and template wiring described above - so an Ansible tree becomes a call graph like
any other repo. Graph files live in the vault's .graph/ and are vault-contained
(resolved + checked to stay inside the vault). Query tools are read-only; local graph_build
deliberately creates or replaces the selected graph artifact. Vault note tools never depend on it.
Shared server mode
Run this only for a central, always-on gateway reachable over the network.
1. Map vaults - cp vaults.example.yaml vaults.yaml, then set name -> path / repo_root / subdir. repo_root + subdir pathspec-scope commits to a vault that lives inside a larger repo.
2. Mint a token per user (the admin does this):
cp tokens.example.yaml tokens.yaml
openssl rand -hex 32 # once PER user -> the key
chmod 0600 tokens.yaml # refused at load if group/world-readable
tokens:
"8f3c…hex…":
sub: alice # identity recorded on that user's commits
vaults: [teamwiki] # the ONLY vaults this token may see/touch
write: true # false = read-only
A token sees only the vaults in its vaults list; anything else returns an opaque
vault_forbidden. vaults.yaml + tokens.yaml are gitignored.
3. Run - uv run knowledge-gateway (127.0.0.1:8765, path /mcp/). For a team box, run it as
a service - see deploy/ and Operate below.
4. Connect - the admin shares the token over a password manager (not chat). Replace this example endpoint with your gateway's MCP URL:
claude mcp add --transport http --scope project teamwiki \
https://gateway.example.com/mcp/ --header "Authorization: Bearer $GW_TOKEN"
Security model
- No secrets in the repo.
vaults.yaml/tokens.yamlare gitignored; only*.example.yamlship.tokens.yamlis refused at load if group/world-readable. - Local mode has no credential surface - a local stdio subprocess; the trust boundary is filesystem access the user already has.
- Server mode authenticates each user with a
StaticTokenVerifierbearer token and enforces per-vault ACLs. Its vault list and write flag determine what the user may access or change. - Path guards on all note I/O via
safe_note_path(traversal, symlink, hidden/dotfiles incl..env, non-.md,.git/.obsidian). Search/backlinks/tags are bounded to*.md. - Server-mode error masking - the HTTP server runs
mask_error_details=True: only the gateway's own expected failures surface asToolError; unexpected OS/git errors are hidden. Local mode keeps details visible. - Commits are attributed to the requesting user (server) or the local git identity (local), and pathspec-scoped to the vault subdir.
Set it up with an AI
Paste this into an agent at a repo's root to wire in local mode:
Add the knowledge-gateway to this repo so agents can read/edit our vault over MCP with zero
tokens:
1. Create or merge `.mcp.json` at the repo root with an mcpServers."wiki" entry that runs:
uvx --refresh --from 'knowledge-gateway[graph]' knowledge-gateway --local
(`--local` auto-detects the vault: ./wiki, a *-obsidian-vault dir, or a dir with .obsidian/.
If detection is ambiguous, use `--vault ./<vault dir>` instead of `--local`.)
2. Verify: `uvx --refresh --from 'knowledge-gateway[graph]' \
knowledge-gateway --help` resolves; then in the agent, call list_vaults and read one note.
Branch + PR, no direct push, no AI attribution.
For the shared server, ask your gateway admin for a token, then run the claude mcp add … from
Connect above.
Operate (servers)
A server runs the latest release as a uv tool, with a daily job that reinstalls and
restarts only when the published version changes. Reference units are in deploy/:
uv tool install 'knowledge-gateway[graph,convert]'
# the binary lives in the uv cache, so point config at the live files via env:
# KNOWLEDGE_GATEWAY_VAULTS= <dir>/vaults.yaml KNOWLEDGE_GATEWAY_TOKENS= <dir>/tokens.yaml
deploy/knowledge-gateway.service- the service (systemd--user).deploy/knowledge-gateway-update.{service,timer}+deploy/auto-update.sh- the daily auto-update.
Update now instead of waiting for the timer:
uv tool install --reinstall 'knowledge-gateway[graph,convert]', then restart the service. Health: curl -s -o /dev/null -w '%{http_code}' http://127.0.0.1:8765/mcp/ -> 401.
Release (maintainers)
Releasing is a version bump, nothing else. release.yml watches for a green ci run on
main whose pyproject.toml version has no tag yet, and then does the rest by itself:
build, publish to PyPI (Trusted Publishing, no token), then create the vX.Y.Z GitHub Release
and immutable tag. No distribution branch is created or moved.
Merging code without a version bump leaves it unreleased. The release workflow can finish successfully while skipping publication when the version's tag, published GitHub Release and matching PyPI artifacts already exist.
- Move
Unreleasedchangelog entries into the new version section and bump the version inpyproject.toml,server.jsonand.claude-plugin/plugin.json. - Run
uv lockso the lockfile carries the new version, plus the skill validator and the test suite. Open a PR; merge only after the Python 3.11-3.13 CI matrix is green. - Watch the
releaserun. Verify the source commit, immutable tag and matching wheel/sdist digests on PyPI and the GitHub Release.
The tag is created after PyPI publishing. GitHub assets use the verified bytes downloaded
from PyPI, with their runtime sources checked against the release tree. An incomplete tagged
release resumes from that tag; published assets with conflicting digests are refused.
If PyPI has the version but its tag is absent, automatic publication stops. Inspect the original
workflow and its source evidence before recovering the immutable tag and retrying. A later
commit must not claim an already published version. Pushing a vX.Y.Z tag by hand remains
supported and checks that the tag matches the packaged version.
Consumers pick it up next session; servers within a day (or restart now).
Develop
uv venv && uv pip install -e ".[dev]"
uv run pytest # ACL + path guards + edit/frontmatter + detect + masking
Metadata
Release files for knowledge-gateway 0.13.0
For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.
Source distribution (sdist)
| File | Size | Uploaded | Provenance | Actions |
|---|---|---|---|---|
| knowledge_gateway-0.13.0.tar.gz | 493.2 kB | With provenance | Details for knowledge_gateway-0.13.0.tar.gz |
Built distribution (wheel)
| File | Interpreter | ABI | Platform | Actions Reset |
|---|---|---|---|---|
| knowledge_gateway-0.13.0-py3-none-any.whl | Python 3 | none | any | Details for knowledge_gateway-0.13.0-py3-none-any.whl |
Total release size: 696.2 kB
Release files / knowledge_gateway-0.13.0.tar.gz
| Download URL | knowledge_gateway-0.13.0.tar.gz |
|---|---|
| Size | 493.2 kB |
| Tags | Source |
|
SHA-256 checksum How to use checksums |
5df9eeb9b06e0a32bdb8748661d45a1d6324d897f697d1e1eede3a960b1c919a
|
|
BLAKE2b-256 checksum How to use checksums |
878fe51e0fae03d7ce501119513a136157dc12ca14fb86dd5b5b42a71d6ccdc8
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
Yes |
| Uploaded via |
twine/7.0.0 CPython/3.13.16
|
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
PyPI Publish Attestation
PyPI verified that this artifact, at this checksum, originated from the publisher listed below.
Signed by GitHub Actions, verified by PyPI on Nov 5, 2026.
Transparency logRelease files / knowledge_gateway-0.13.0-py3-none-any.whl
| Download URL | knowledge_gateway-0.13.0-py3-none-any.whl |
|---|---|
| Size | 202.9 kB |
| Tags | Python 3 |
|
SHA-256 checksum How to use checksums |
0a4d2cd2b852ec384ff0af60ea9601c7230c540ea3c3d170ab25291c77974344
|
|
BLAKE2b-256 checksum How to use checksums |
629780fbdcf0f292c763fc9acfccd29e098c500df9528611c6daa635ddb15560
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
Yes |
| Uploaded via |
twine/7.0.0 CPython/3.13.16
|
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
PyPI Publish Attestation
PyPI verified that this artifact, at this checksum, originated from the publisher listed below.
Signed by GitHub Actions, verified by PyPI on Nov 5, 2026.
Transparency logSecurity for knowledge-gateway 0.13.0
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
Full provenance
Both files in this release have been uploaded with provenance metadata.
Attestation for knowledge_gateway-0.13.0.tar.gz
PyPI Publish Attestation
PyPI verified that this artifact, at this checksum, originated from the publisher listed below.
Signed by GitHub Actions, verified by PyPI on Nov 5, 2026.
Transparency logA note on package security
PyPI is a repository for distributing packages, not a service for auditing them. While third-party security researchers and our staff do their best to detect and remove malicious packages, PyPI cannot guarantee the quality, security or suitability of any given package.
To learn more about protecting yourself from malicious actors, visit our package security documentation.