io.github.yourtechtribe-labs/koncept-mcp-server — MCP Server

This Model Context Protocol (MCP) server queries a curated YAML semantic concept graph for codebase invariants and cross-cutting facts. It focuses on meaning-oriented context rather than only structural relationships. Package metadata and topics are aligned to code intelligence workflows, including semantic search and TypeScript tooling.

🛠️ Key Features

Queries a curated YAML semantic concept graph
Provides codebase invariants
Supports cross-cutting facts

🚀 Use Cases

Extract and reuse semantic concepts about a codebase
Find invariants and cross-cutting information across a repository (e.g., monorepos)

⚡ Developer Benefits

Works with semantic-search and concept-graph workflows
Uses YAML-based graph data for code intelligence
Fits MCP (Model Context Protocol) integrations for model-context queries

⚠️ Limitations

Source data excerpt only confirms graph querying; specific APIs/tools and tool behavior are not shown here

📦 Topics

ai-tools, claude, claude-code, cli, code-intelligence, concept-graph, mcp, model-context-protocol, modelcontextprotocol, monorepo, pnpm, semantic-search, typescript, yaml

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

bash

# 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:

yaml

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.

io.github.yourtechtribe-labs/koncept-mcp-server