Koncept Mcp

koncepto

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

[]() []() []() [](https://scorecard.dev/viewer/?uri=github.com/yourtechtribe-labs/koncept-mcp)

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](./ROADMAP.md).

Dogfooded against this repo itself: 5 concepts in [.koncept/concepts/](./.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 project
pnpm add -D @yourtechtribe-labs/koncept-cli@alpha

# Bootstrap
npx koncepto init

# Write a concept (YAML)
$EDITOR .koncept/concepts/my-concept.yaml

# Verify
npx 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](./LICENSE).

Source & license

This open-source MCP server is cataloged on AgentStack and links to its original source — we do not rehost the code.

• Author: yourtechtribe-labs
• Source: yourtechtribe-labs/koncept-mcp
• License: MIT
• Homepage: https://www.npmjs.com/package/@yourtechtribe-labs/koncept-cli

Install and usage instructions live in the source repository linked above.