{"_id":"@adaniki/contract-agent-linter","_rev":"3-36a313ff116f2c2708e6ea4d5a8b3a84","name":"@adaniki/contract-agent-linter","dist-tags":{"latest":"0.2.1"},"versions":{"0.1.0":{"name":"@adaniki/contract-agent-linter","version":"0.1.0","keywords":["mcp","model-context-protocol","contract","linter","ai","claude","yaml","architecture","dependency-graph","validation"],"author":{"name":"adaniki-dev"},"license":"MIT","_id":"@adaniki/contract-agent-linter@0.1.0","maintainers":[{"name":"adaniki","email":"ikiyoshikai@gmail.com"}],"homepage":"https://github.com/adaniki-dev/contract-mcp#readme","bugs":{"url":"https://github.com/adaniki-dev/contract-mcp/issues"},"bin":{"contract-agent-linter":"dist/server.js","contract-agent-linter-check":"dist/check-commit.js"},"dist":{"shasum":"790e81f944247b92f61ee2648b93a457134c21ac","tarball":"https://registry.npmjs.org/@adaniki/contract-agent-linter/-/contract-agent-linter-0.1.0.tgz","fileCount":7,"integrity":"sha512-3abHG5Yse/ljDj3EFH3a6LjXkIYxIx7BUJy+VE32NYeCX6vrROx+IUkgqAytARaj2ngvp270mobQ97k8WwUpRw==","signatures":[{"sig":"MEUCIQCVnTZoibynWkbpOfpD5Eygop0K7bXTDy1C9MhA8qWrgQIgXdopklNAFP0R2+gW/AH7OSC71nPgjLZpv+94feSL9mA=","keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U"}],"unpackedSize":739897},"main":"dist/server.js","type":"module","engines":{"bun":">=1.0.0"},"gitHead":"a06e3f8d815292be8c99d0f8fa5e4af637859a34","scripts":{"dev":"bun run src/app/index.ts","test":"bun test","build":"bun run scripts/build.ts","typecheck":"tsc --noEmit","test:watch":"bun test --watch","prepublishOnly":"bun run build"},"_npmUser":{"name":"adaniki","email":"ikiyoshikai@gmail.com"},"repository":{"url":"git+https://github.com/adaniki-dev/contract-mcp.git","type":"git"},"_npmVersion":"11.11.0","description":"MCP server that acts as a contract linter for AI agents. Understand projects through structured YAML contracts instead of reading raw files.","directories":{},"_nodeVersion":"24.14.1","dependencies":{"yaml":"^2.7.1","oxc-parser":"^0.65.0","es-module-lexer":"^1.6.0","@modelcontextprotocol/sdk":"^1.12.1"},"_hasShrinkwrap":false,"devDependencies":{"@types/bun":"^1.2.9","typescript":"^5.8.3"},"_npmOperationalInternal":{"tmp":"tmp/contract-agent-linter_0.1.0_1776114572274_0.054494522837529535","host":"s3://npm-registry-packages-npm-production"}},"0.2.0":{"name":"@adaniki/contract-agent-linter","version":"0.2.0","keywords":["mcp","model-context-protocol","contract","linter","ai","claude","yaml","architecture","dependency-graph","validation"],"author":{"name":"adaniki-dev"},"license":"MIT","_id":"@adaniki/contract-agent-linter@0.2.0","maintainers":[{"name":"adaniki","email":"ikiyoshikai@gmail.com"}],"homepage":"https://github.com/adaniki-dev/contract-mcp#readme","bugs":{"url":"https://github.com/adaniki-dev/contract-mcp/issues"},"bin":{"contract-agent-linter":"dist/server.js","contract-agent-linter-check":"dist/check-commit.js"},"dist":{"shasum":"2caaeb8e3d87487e9772dadcb8fee6939f007766","tarball":"https://registry.npmjs.org/@adaniki/contract-agent-linter/-/contract-agent-linter-0.2.0.tgz","fileCount":7,"integrity":"sha512-d9abLbVKSdrJLvpLIPjO5zbzOF2DMzfKUgxWwfuQkHQodY+X++iAScbzsIxrej5uvB+Fo6b/t60TrACtM3XQTQ==","signatures":[{"sig":"MEUCIQD83eH2p3yx8GCvpVyhGMKKfzyQpUSg3Ctul9CoxPlyqAIgBWnSnRsZbllUwWcnyFeePeYq6asfjU99CquBQCq6Jmw=","keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U"}],"unpackedSize":747289},"main":"dist/server.js","type":"module","engines":{"bun":">=1.0.0"},"gitHead":"e6e366561c8397ae0efe5f8892e20a68c2708aa7","scripts":{"dev":"bun run src/app/index.ts","test":"bun test","build":"bun run scripts/build.ts","typecheck":"tsc --noEmit","test:watch":"bun test --watch","prepublishOnly":"bun run build"},"_npmUser":{"name":"adaniki","email":"ikiyoshikai@gmail.com"},"repository":{"url":"git+https://github.com/adaniki-dev/contract-mcp.git","type":"git"},"_npmVersion":"11.11.0","description":"MCP server that acts as a contract linter for AI agents. Understand projects through structured YAML contracts instead of reading raw files.","directories":{},"_nodeVersion":"24.14.1","dependencies":{"yaml":"^2.7.1","oxc-parser":"^0.65.0","es-module-lexer":"^1.6.0","@modelcontextprotocol/sdk":"^1.12.1"},"_hasShrinkwrap":false,"devDependencies":{"@types/bun":"^1.2.9","typescript":"^5.8.3"},"_npmOperationalInternal":{"tmp":"tmp/contract-agent-linter_0.2.0_1776194726580_0.08460626888333578","host":"s3://npm-registry-packages-npm-production"}},"0.2.1":{"name":"@adaniki/contract-agent-linter","version":"0.2.1","description":"MCP server that acts as a contract linter for AI agents. Understand projects through structured YAML contracts instead of reading raw files.","type":"module","main":"dist/server.js","bin":{"contract-agent-linter":"dist/server.js","contract-agent-linter-check":"dist/check-commit.js"},"scripts":{"dev":"bun run src/app/index.ts","build":"bun run scripts/build.ts","test":"bun test","test:watch":"bun test --watch","typecheck":"tsc --noEmit","prepublishOnly":"bun run build"},"keywords":["mcp","model-context-protocol","contract","linter","ai","claude","yaml","architecture","dependency-graph","validation"],"author":{"name":"adaniki-dev"},"license":"MIT","repository":{"type":"git","url":"git+https://github.com/adaniki-dev/contract-mcp.git"},"bugs":{"url":"https://github.com/adaniki-dev/contract-mcp/issues"},"homepage":"https://github.com/adaniki-dev/contract-mcp#readme","engines":{"bun":">=1.0.0"},"dependencies":{"@modelcontextprotocol/sdk":"^1.12.1","es-module-lexer":"^1.6.0","oxc-parser":"^0.65.0","yaml":"^2.7.1"},"devDependencies":{"@types/bun":"^1.2.9","typescript":"^5.8.3"},"gitHead":"a2ee97d738538206a169c3ee4ad37c2412fcdbfa","_id":"@adaniki/contract-agent-linter@0.2.1","_nodeVersion":"24.14.1","_npmVersion":"11.11.0","dist":{"integrity":"sha512-xRe9uEVpBTz9Uq6qqWlVO++EquupERnbkvGecCot2qbVu1qMnQMsGxFfaj6Fs6SqgFguaFd6qLJhuCZCNm8pyg==","shasum":"ceb80237f3870da4037c35d4ef29d40c40fcb8bf","tarball":"https://registry.npmjs.org/@adaniki/contract-agent-linter/-/contract-agent-linter-0.2.1.tgz","fileCount":7,"unpackedSize":747314,"signatures":[{"keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U","sig":"MEYCIQCfR6k2DNSY0iq/YiJ9hnhnoQg5xHeFtEB/GydL/P2z8gIhAPQR0xp/Xx5zZDVKVCZsgQMn5p0vSMLbwZK4LPHuhgmI"}]},"_npmUser":{"name":"adaniki","email":"ikiyoshikai@gmail.com"},"directories":{},"maintainers":[{"name":"adaniki","email":"ikiyoshikai@gmail.com"}],"_npmOperationalInternal":{"host":"s3://npm-registry-packages-npm-production","tmp":"tmp/contract-agent-linter_0.2.1_1776198811730_0.22817704619793866"},"_hasShrinkwrap":false}},"time":{"created":"2026-04-13T21:09:32.125Z","modified":"2026-04-14T20:33:31.998Z","0.1.0":"2026-04-13T21:09:32.400Z","0.2.0":"2026-04-14T19:25:26.722Z","0.2.1":"2026-04-14T20:33:31.883Z"},"bugs":{"url":"https://github.com/adaniki-dev/contract-mcp/issues"},"author":{"name":"adaniki-dev"},"license":"MIT","homepage":"https://github.com/adaniki-dev/contract-mcp#readme","keywords":["mcp","model-context-protocol","contract","linter","ai","claude","yaml","architecture","dependency-graph","validation"],"repository":{"type":"git","url":"git+https://github.com/adaniki-dev/contract-mcp.git"},"description":"MCP server that acts as a contract linter for AI agents. Understand projects through structured YAML contracts instead of reading raw files.","maintainers":[{"name":"adaniki","email":"ikiyoshikai@gmail.com"}],"readme":"

\n \"MCP\n
\n \"Bun\"\n \"TypeScript\"\n \"MCP\"\n \"YAML\"\n \"XML\"\n \"9\n

\n\n# MCP Contractor\n\n> **AI agents shouldn't guess. They should read the contract.**\n\nMCP Contractor is a Model Context Protocol server that acts as a **contract linter for AI**. Instead of relying on `ls`, `find`, or scanning raw files, AI agents call MCP Contractor to understand a project through structured YAML contracts.\n\nEach contract defines a feature's **dependencies**, **exports**, **business rules**, **file structure**, and **types** -- giving the AI everything it needs to work without breaking things.\n\n---\n\n## Why\n\nAI agents working on large codebases often:\n- Break dependencies they didn't know existed\n- Forget business rules buried in code comments\n- Produce code that doesn't follow project conventions\n- Lose context across feature boundaries\n\n**MCP Contractor solves this** by making contracts the source of truth. The AI reads the contract before touching the code.\n\n---\n\n## How It Works\n\n```\n Developer AI Agent (Claude Code)\n | |\n | writes contracts (.yaml) |\n |----------------------------->|\n | | calls MCP tools\n | |----------------> MCP Contractor\n | | |\n | | <-- XML response |\n | | (deps, rules, |\n | | exports, types) |\n | | |\n | writes code that | |\n | <-- respects contracts | |\n | | |\n | opens dashboard (browser) | |\n |----------------------------->| http://localhost:8000\n```\n\n---\n\n## MCP Tools\n\n9 tools available, organized by workflow:\n\n### Discovery\n\n| Tool | Description |\n|------|-------------|\n| `search` | Search contracts with filters (query, status, dependsOn, dependedBy, owner, hasRules, hasViolations) |\n| `get_feature` | Get the full contract of a feature as optimized XML |\n| `get_dependencies` | Get dependency graph (direct + transitive + circular detection) |\n\n### Analysis\n\n| Tool | Description |\n|------|-------------|\n| `compile` | Compile all contracts, return XML diagnostic report |\n| `validate` | Verify implementation code matches contract declarations |\n| `drift` | Detect drift between the index and actual contract files |\n| `index` | Generate or update the contracts YAML index |\n\n### Mutation\n\n| Tool | Description |\n|------|-------------|\n| `scaffold` | Generate a YAML contract template for a new feature (configurable `basePath`) |\n| `update` | Modify an existing contract (metadata, deps, rules, files) |\n\n### Onboarding\n\n| Tool | Description |\n|------|-------------|\n| `reference` | Get contract-driven development guide. Sections: `workflow`, `tools`, `rules`, `claude-md` |\n\nAll responses are **token-optimized XML** -- compact, action-oriented, no redundancy.\n\n### Example Workflows\n\n**AI exploring a new codebase:**\n```\nsearch({ status: \"active\" }) -> overview of active features\nget_feature({ feature: \"auth\" }) -> full contract details\nget_dependencies({ feature: \"auth\" }) -> what auth depends on\n```\n\n**AI before modifying code:**\n```\nsearch({ dependsOn: \"database\" }) -> who depends on database?\nvalidate({ feature: \"database\" }) -> is database currently valid?\nget_feature({ feature: \"database\" }) -> read the rules before changing\n```\n\n**AI creating a new feature:**\n```\nscaffold({ feature: \"payments\", basePath: \"src/modules\", deps: \"auth,database\" })\nupdate({ feature: \"payments\", addRules: \"idempotent-charges\", status: \"draft\" })\nvalidate({ feature: \"payments\" })\n```\n\n**AI checking health:**\n```\ncompile() -> any broken contracts?\ndrift() -> index up to date?\nsearch({ hasViolations: true }) -> which features have problems?\n```\n\n---\n\n## Search Filters\n\nThe `search` tool supports combining multiple filters for precise queries:\n\n| Filter | Type | Description |\n|--------|------|-------------|\n| `query` | string | Text search across all fields (name, description, deps, exports, rules, files) |\n| `status` | string | Filter by `draft`, `active`, or `deprecated` |\n| `dependsOn` | string | Find features that depend on this feature |\n| `dependedBy` | string | Find features that this feature depends on |\n| `owner` | string | Filter by contract owner |\n| `hasRules` | string | Find features with rules matching this ID |\n| `hasViolations` | boolean | `true` = only broken features, `false` = only clean |\n\nAll filters are combinable: `search({ dependsOn: \"compiler\", status: \"active\" })`\n\n---\n\n## Web Dashboard (for Humans)\n\nA live dashboard auto-starts on `localhost:8000` (auto-fallback to next port if busy):\n\n| View | URL | Description |\n|------|-----|-------------|\n| **Summary** | `/` | Status bar, metric cards, features table with inline violations |\n| **Project** | `/project` | Tree view of contracts + humanized contract detail cards |\n| **Brain Link** | `/graph` | Interactive force-directed dependency graph (Canvas 2D, drag & hover) |\n\nAPI endpoints for integration:\n- `GET /api/data` -- Dashboard summary (JSON)\n- `GET /api/contracts` -- All compiled contracts (JSON)\n- `GET /api/graph` -- Dependency graph nodes + edges (JSON)\n\n---\n\n## Contract Validation\n\nThe validator checks your code against its contracts:\n\n- **exports-match** -- Barrel exports must match what the contract declares\n- **deps-declared** -- Imports from other features must be declared in dependencies\n- **no-circular-deps** -- Circular dependencies between features are detected\n- **files-exist** -- Declared files must exist in the filesystem\n\nFeature discovery is dynamic -- the validator searches `src/**/features/{name}/` and `src/**/{name}/` to find feature directories, supporting any project structure.\n\n---\n\n## Contract Discovery\n\nContracts are scanned from two locations:\n\n- `contracts/` -- Centralized project-wide contracts (flat scan)\n- `src/**/` -- Feature-local contracts colocated with code (recursive `**/*.contract.yaml`)\n\nIgnored directories: `node_modules`, `dist`, `build`, `.git`, `.next`, `.nuxt`, `.svelte-kit`, `coverage`, `.turbo`, `.cache`\n\n---\n\n## Quick Start\n\n### Install\n\n```bash\nbun install\n```\n\n### Connect to Claude Code\n\nCreate `.mcp.json` in your project root:\n\n```json\n{\n \"mcpServers\": {\n \"contract-mcp\": {\n \"command\": \"bun\",\n \"args\": [\"run\", \"src/app/index.ts\"],\n \"cwd\": \"/path/to/contract-mcp\"\n }\n }\n}\n```\n\nRestart Claude Code. You'll see 10 new tools available. The dashboard opens automatically at **http://localhost:8000**.\n\n### Run Standalone\n\n```bash\nbun run dev # Start MCP server (stdio)\n```\n\n---\n\n## Contract Anatomy\n\nEvery feature has a `.contract.yaml` that follows this structure:\n\n```yaml\ncontract:\n version: \"1.0.0\"\n feature: auth\n description: \"Authentication and authorization\"\n owner: backend-team\n status: active # draft | active | deprecated\n\ndependencies:\n internal:\n - feature: database\n reason: \"Stores user sessions and credentials\"\n external:\n - package: bcrypt\n version: \"^5.1.0\"\n reason: \"Password hashing\"\n\nexports:\n functions:\n - name: authenticate\n signature: \"(credentials: Credentials) => Result\"\n description: \"Validates credentials and returns a token\"\n pure: true\n types:\n - name: AuthToken\n description: \"JWT token wrapper with expiry\"\n\nrules:\n - id: token-expiry\n description: \"Tokens must expire within 24 hours\"\n severity: error # error | warning | info\n testable: true\n - id: rate-limit\n description: \"Max 5 failed attempts per minute per IP\"\n severity: error\n testable: true\n\nfiles:\n - path: src/features/auth/index.ts\n purpose: \"Barrel export\"\n - path: src/features/auth/auth.ts\n purpose: \"Core authentication logic\"\n```\n\nThe `scaffold` tool generates this template automatically:\n```\nscaffold({ feature: \"auth\", basePath: \"src/modules\", deps: \"database,crypto\", owner: \"backend-team\" })\n```\n\n---\n\n## XML Output (for AI)\n\nResponses are optimized for token efficiency:\n\n```xml\n\n\n\nVerifica se o codigo corresponde aos contratos\nWeb dashboard humanizado\n\n\n```\n\nOne line per result. Attributes for data, text content for descriptions. Maximum information, minimum tokens.\n\n---\n\n## License\n\nMIT\n","readmeFilename":"README.md"}