Koncept Mcp Server

koncepto

Semantic concept graph MCP server for codebases — what your code means, not just what it does.

[Status] [License] [pnpm] [OpenSSF Scorecard]

What

Code graphs (Aider repomap, GitNexus, Sourcegraph) capture structural relations: who imports who, who calls who. They miss semantic invariants — the cross-cutting concepts that live in code not related by imports:

• "Fix B" lives in 7 files but isn't a function or a class
• "All UI counting workload must exclude manual-override participants"
• "Sector value strings must match SectorAssignment.sector keys exactly"

koncepto is the curated semantic layer. Concepts in YAML, queryable via MCP tools, read at Step 0 before editing.

Status

Pre-alpha (v0.1.0-alpha.3 on npm). Schema and tool surface may break before 0.1.0 final. See roadmap.

Dogfooded against this repo itself: 5 concepts in .koncept/concepts/ cover the schema, the registry, the MCP tool contract, the monorepo shape, and the kebab-id naming convention. pnpm dogfood = koncepto verify against its own registry.

Quickstart

# Install in your projectpnpm add -D @yourtechtribe-labs/koncept-cli@alpha
# Bootstrapnpx koncepto init
# Write a concept (YAML)$EDITOR .koncept/concepts/my-concept.yaml
# Verifynpx koncepto verify
# Register MCP server (Claude Code)claude mcp add --scope user koncepto -- \  npx -y @yourtechtribe-labs/koncept-mcp-server@alpha "$PWD"

Enforced invariants

An invariant is advisory by default — surfaced to agents via koncept_for_file, but never evaluated. Give it a check and it becomes an enforced gate that koncepto verify fails on:

invariants:  - id: invalidate-projection-cache    description: A standalone sync that invalidates the banking cache must also      invalidate the projection cache, or the /cashflow opening balance goes stale.    severity: high    check:      kind: implication        # per participant file: if it matches `if`, it must also match `then`      over: { role: writer }      if: "BankingCacheService"      then: "CacheInvalidationService|on_full_sync"

Static kinds (implication, symbol_present, forbidden, grep) run on koncepto verify by default (fast, read-only; --no-checks to skip). The shell escape hatch (kind: command) runs only on koncepto check. This turns a "completion-contract" concept into both the checklist and its enforcement gate — the loose end can't be skipped under momentum.

Architecture

3 packages under pnpm workspace:

• @yourtechtribe-labs/koncept-core — Zod schema, YAML parser, indexer
• @yourtechtribe-labs/koncept-mcp-server — MCP stdio server (4 tools)
• @yourtechtribe-labs/koncept-cli — init, verify, list, link

License

MIT — see LICENSE.