Skip to main content
Glama
3ii-factory

spec-drift-mcp

by 3ii-factory
OverviewSchemaRelated ServersScoreDiscussions
TypeScript
Local

spec-drift-mcp

English version / 英語版はこちら

AIコーディングエージェントが、コードを書く前・コミットする前に、自分の仕事を仕様書と突き合わせて自己チェックできるようにする MCP サーバーです。

データ構造の「正」を小さなYAML仕様書（SSOT: 唯一の正）として持っておくと、エージェントは Model Context Protocol 経由でこう聞けるようになります:

  • 「Invoice ってどういう形であるべき？」 → explain_spec

  • 「今のコード、仕様とズレてない？」 → check_drift

返ってくるのは推測ではなく、機械的に検証された答えです — 足りないフィールド、仕様にない余計なフィールド、型の不一致。

なぜ作ったか

私は業務管理SaaS（約53,000行）を本番運用しています。開発体制はほぼ1人＋AIコーディングエージェント。そこで一番痛かった失敗は、下手なコードではなく**静かなズレ（silent drift）**でした。仕様書はAと言っているのに、コードはいつの間にかBというフィールドを生やしていて、誰も気づかないまま本番でデータが欠ける — そういう事故です。

効いた対策は、仕様書を「エージェントが自分で参照でき、採点もされる存在」に変えること。pre-commitフックに組み込んで、ズレたままのコミットを機械的に止める。本リポジトリは、その仕組みからプロジェクト固有のコードを取り除き、単体のMCPサーバーとして切り出したものです。

Related MCP server: CodeGuardian MCP

インストール

npm install -g spec-drift-mcp
# またはインストールせずに実行:
npx spec-drift-mcp

Node.js 18以上が必要です。

Claude Code で使う

claude mcp add spec-drift -- npx -y spec-drift-mcp

…または任意のMCPクライアント（Claude Desktop等）に設定で追加:

{
  "mcpServers": {
    "spec-drift": {
      "command": "npx",
      "args": ["-y", "spec-drift-mcp"],
      "env": {
        "SPEC_DRIFT_ROOT": "/absolute/path/to/your/project",
        "SPEC_DRIFT_SPECS": "specs"
      }
    }
  }
}

  • SPEC_DRIFT_ROOT — 各仕様書の source パスの基準になるプロジェクトルート（デフォルト: カレントディレクトリ）

  • SPEC_DRIFT_SPECS — 仕様書の置き場所。ルートからの相対パス（デフォルト: specs）

ツール一覧

ツール

何をするか

list_specs

全エンティティの仕様書と、それが管理するソースシンボルを一覧する

explain_spec

1エンティティのフィールドレベルの仕様全文を返す

check_drift

仕様書と実際のTypeScriptソースを比較し、すべてのズレを報告する

仕様書のフォーマット

仕様書ディレクトリに、1エンティティ = 1 YAMLファイル:

entity: Invoice          # 論理名。explain_spec / check_drift が使う
symbol: Invoice          # 検査対象のTSインターフェース or 型エイリアス（省略時はentityと同じ）
source: src/models/invoice.ts   # ソースファイルへのパス（ルートからの相対）
fields:
  - name: id
    type: string
  - name: amount
    type: number
  - name: issuedAt
    type: string
  - name: paid
    type: boolean

「コード側」は ts-morph でTypeScriptソースから直接読み取ります — symbol で指名された interface またはオブジェクトリテラルの type エイリアスが対象です。

ズレの検出例

リポジトリ同梱の examples/ では、Customer がわざと仕様からズレています。check_drift は3種類すべてを検出します:

{
  "ok": false,
  "checked": 2,
  "totalFindings": 3,
  "reports": [
    {
      "entity": "Customer",
      "findings": [
        { "kind": "MISSING_IN_CODE", "field": "email",        "expected": "string" },
        { "kind": "TYPE_MISMATCH",   "field": "creditLimit",  "expected": "number", "actual": "string" },
        { "kind": "EXTRA_IN_CODE",   "field": "emailAddress", "actual": "string" }
      ]
    },
    { "entity": "Invoice", "ok": true, "findings": [] }
  ]
}

  • MISSING_IN_CODE — 仕様書にあるフィールドがコードに無い

  • EXTRA_IN_CODE — コードにあるフィールドが仕様書に無い

  • TYPE_MISMATCH — フィールドはあるが型が違う

CLIとしても使える（pre-commit / CI用）

同じチェックがエージェント無しでも走ります。ズレがあれば非ゼロで終了するので、コミットのゲートにできます:

spec-drift-mcp check --root . --specs examples/specs
x Customer (Customer) - 3 drift
    [MISSING_IN_CODE] field 'email' is declared in the spec but missing in Customer
    [TYPE_MISMATCH] field 'creditLimit' should be 'number' but Customer has 'string'
    [EXTRA_IN_CODE] field 'emailAddress' exists in Customer but is not declared in the spec
ok Invoice (Invoice) - in sync

spec-drift: 3 problem(s) across 2 spec(s)

.git/hooks/pre-commit に入れるなら:

#!/usr/bin/env sh
npx spec-drift-mcp check || {
  echo "仕様とコードにズレがあります — コードを仕様に合わせてからコミットしてください"
  exit 1
}

仕組み

 YAML仕様書 (SSOT) ─┐
                    ├─►  比較  ─►  検出結果（欠落 / 余剰 / 型不一致）
 TSソース (現実)   ─┘
   ts-morphで読み取り

  1. spec.ts がYAML仕様書を読み込み、検証する（zod）

  2. extract.ts がts-morphでTypeScriptソースから実際のフィールド構成を読み取る

  3. drift.ts が両者を突き合わせ、ズレを検出する

  4. server.ts がそれをMCPとして公開。cli.ts が同じものをフック/CI向けに公開

開発

npm install
npm run typecheck   # tsc --noEmit
npm test            # vitest
npm run build       # tsup -> dist/index.js
npm run smoke       # ビルド済みサーバーを実MCPプロトコルで叩いて検証

ライセンス

MIT © 3ii-factory

Available Tools

3 tools
check_driftCheck spec/code driftA

Compare the spec against the actual TypeScript source and report every drift: fields missing in code, extra fields absent from the spec, and type mismatches. Run this before committing, or right after editing a spec-controlled type.

ParametersJSON Schema
NameRequiredDescriptionDefault
rootNoproject root the spec 'source' paths are relative to
entityNolimit the check to one entity
specDirNo

TDQS

A3.6/5.0
Behavior2/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

No annotations are provided, so the description must disclose all behavioral traits. It describes a read-only comparison but doesn't explicitly state non-destructiveness, permissions, or side effects. Insufficient for a tool with no annotation support.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

Two sentences with no wasted words. First sentence defines action and scope, second gives usage timing. Efficient and well-structured.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness3/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

The description covers basic purpose and usage timing but omits return format, error conditions, and behavioral details (e.g., what happens when no drift is found). For a tool with no output schema and no annotations, more completeness is needed.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters2/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is 67% (2 of 3 parameters have descriptions). The description adds no extra meaning beyond the schema; it doesn't document the undocumented specDir parameter. No value added over schema.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states the tool compares spec against TypeScript source and reports drift, listing specific types of mismatches. This distinguishes it from sibling tools like explain_spec and list_specs.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines4/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

Explicitly says to run before committing or after editing a spec-controlled type, providing clear usage context. No mention of when not to use, but siblings are unrelated, so no need for alternatives.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

explain_specExplain specB

Return the full field-level spec for one entity so you know exactly what to implement before writing code.

ParametersJSON Schema
NameRequiredDescriptionDefault
entityYesentity name, e.g. 'Invoice'
specDirNo

TDQS

B3.4/5.0
Behavior3/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

No annotations are provided, so the description carries the full burden. It states a read-only action ('Return the full field-level spec'), but does not disclose any other behavioral traits such as whether data is fetched from a source, authentication requirements, rate limits, or side effects. Acceptable but minimal.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness4/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is a single sentence, front-loaded with the essential purpose. It is very concise, though it could be slightly more structured to separate purpose from usage hint.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness2/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

With no output schema and two parameters (one undocumented), the description does not explain what the returned 'field-level spec' contains or how the 'specDir' parameter affects the result. This leaves significant gaps for an agent to correctly interpret the response.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters2/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Only 50% of parameters are described in the schema (entity has a description; specDir does not). The description adds no parameter details beyond mentioning 'one entity', so it fails to compensate for the undocumented 'specDir' parameter.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states it returns the full field-level spec for one entity, using a specific verb ('Return') and resource ('spec'). It distinguishes itself from siblings like 'list_specs' (which lists specs) and 'check_drift' (which checks for changes).

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines3/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description implies usage before writing code ('so you know exactly what to implement before writing code'), but provides no explicit guidance on when to use this tool versus alternatives like 'list_specs' or 'check_drift', nor does it mention any conditions or restrictions.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

list_specsList specsA

List every entity spec (the single source of truth) and the source symbol it governs. Call this first to see which types are spec-controlled.

ParametersJSON Schema
NameRequiredDescriptionDefault
specDirNooverride the spec directory (relative to the project root)

TDQS

A3.9/5.0
Behavior3/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

No annotations are provided, so the description carries full burden. It describes the output (list of specs with symbols) but does not disclose any behavioral traits like auth requirements, rate limits, or side effects. It is adequate but not thorough.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

Two sentences, each serving a clear purpose: stating the action and providing usage context. No fluff, front-loaded with key information.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness3/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Given no output schema, the description should clarify the return format. It only says 'list... and the source symbol,' leaving ambiguity about structure. For a tool intended as a first step, more detail on output would help.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters3/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema coverage is 100%, so baseline is 3. The description's mention of 'override the spec directory (relative to the project root)' adds no new information beyond the schema's parameter description. Thus, it does not improve semantic clarity.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states what the tool does: it lists every entity spec and the source symbol it governs. It also differentiates from siblings (check_drift, explain_spec) by indicating this is a discovery tool to be called first.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines4/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description explicitly says 'Call this first to see which types are spec-controlled,' providing clear when-to-use guidance. It does not mention when not to use or alternatives, but the context is sufficient.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections. Dates show when Glama detected each change.

  1. 3 tool updatesv0.1.0
    • First observedcheck_drift
    • First observedexplain_spec
    • First observedlist_specs
Install Server
RayrunBuild, deploy, and operate MCP servers without becoming an infrastructure team.ray.runAd

TDQS

A3.9/5.0
Disambiguation5/5

Each tool has a clear, distinct purpose: listing specs, explaining a spec, and checking drift. No overlap or ambiguity.

Naming Consistency5/5

All tools follow a consistent verb_noun pattern with underscores: list_specs, explain_spec, check_drift.

Tool Count4/5

Three tools is minimal but appropriate for the focused domain of spec drift detection. Each tool is essential and well-scoped.

Completeness5/5

The set covers the full workflow: list available specs, get detailed spec, and check for drift. No obvious missing operations for the stated purpose.

Maintenance

ActivitySlowing
ResponsivenessSyncing

Resources

Unclaimed servers have limited discoverability.

Looking for Admin?

If you are the server author, to access and configure the admin panel.

Related MCP Connectors

Related MCP Servers

  • Carrot AI PM

    talvinder
    A
    license
    D
    quality
    D
    maintenance
    Spec-driven development tool for AI coding assistants that generates specs, validates code compliance, and provides actionable feedback.
    11
    29
    MIT

  • MCP Contractor

    adaniki-dev
    A
    license
    Not graded
    quality
    D
    maintenance
    A contract linter for AI agents that uses structured YAML contracts to define dependencies, business rules, and exports, enabling agents to work without breaking project conventions.
    16
    MIT
  • Rigour MCP by rigour-labs

    Rigour MCPofficial

    rigour-labs
    A
    license
    Not graded
    quality
    B
    maintenance
    Enables AI agents to self-govern by scanning code for hardcoded secrets, structural violations, and AI drift in real-time, providing fix packets for automatic remediation.
    26
    MIT

Latest Blog Posts

MCP directory API

We provide all the information about MCP servers via our MCP API.

curl -X GET 'https://glama.ai/api/mcp/v1/servers/3ii-factory/spec-drift-mcp'

If you have feedback or need assistance with the MCP directory API, please join our Discord server