koncept-mcp-server

koncepto

コードベース向けのセマンティックコンセプトグラフ MCP サーバー — コードが何をするかだけでなく、何を意味するかを捉えます。

概要

コードグラフ（Aider repomap、GitNexus、Sourcegraph）は、誰が誰をインポートし、誰が誰を呼び出すかといった構造的な関係を捉えます。一方で、インポートによる関連がないコードに存在する、横断的な概念である意味的な不変条件は見逃します。

• 「Bを修正する」は7つのファイルにまたがりますが、関数でもクラスでもありません
• 「すべてのUIの負荷計算では、手動オーバーライドされた参加者を除外する必要があります」
• 「セクターの値文字列は、SectorAssignment.sector のキーと完全に一致する必要があります」

koncepto は、厳選されたセマンティックレイヤーです。YAMLで記述されたコンセプトをMCPツールから検索でき、編集前のステップ0で読み取れます。

ステータス

プレアルファ（npmでv0.1.0-alpha.3）。スキーマとツールのインターフェースは、0.1.0の正式リリース前に変更される可能性があります。ロードマップをご覧ください。

このリポジトリ自体で実際に利用しています。.koncept/concepts/にある5つのコンセプトで、スキーマ、レジストリ、MCPツールの契約、モノレポの構造、kebab-idの命名規則を網羅しています。pnpm dogfoodを実行すると、自身のレジストリに対してkoncepto verifyを実行します。

クイックスタート

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

適用される不変条件

不変条件は、デフォルトでは参考情報です。koncept_for_fileを通じてエージェントに提示されますが、評価は行われません。checkを指定すると適用ゲートとなり、失敗するとkoncepto verifyも失敗します。

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"

静的な種類（implication、symbol_present、forbidden、grep）は、デフォルトでkoncepto verifyの実行時にチェックされます（高速で読み取り専用です。スキップするには--no-checksを指定します）。シェルによる代替手段（kind: command）は、koncepto checkでのみ実行されます。これにより、「完了条件」を定義するコンセプトが、チェックリストであると同時に適用ゲートにもなります。作業の勢いに押されて、未完了の項目が見過ごされることはありません。

アーキテクチャ

pnpmワークスペース内の3つのパッケージで構成されています。

• @yourtechtribe-labs/koncept-core — Zodスキーマ、YAMLパーサー、インデクサー
• @yourtechtribe-labs/koncept-mcp-server — MCP stdio サーバー（4つのツール）
• @yourtechtribe-labs/koncept-cli — init、verify、list、link

ライセンス

MIT — LICENSEをご覧ください。