mcp-code

🇬🇧 English | 🇹🇷 Türkçe

Semantic MCP server for AI coding agents that resolves the right code slice, plans bounded edits, predicts impact, and routes scoped verification.

Why mcp-code?

• Reduce low-value repository exploration with slice-first semantic workflows.
• Separate planning from mutation so edits stay reviewable and bounded.
• Predict blast radius before changes spread into unrelated code.
• Run the smallest useful verification set first, then escalate only when needed.
• Build on top of @vaur94/mcpbase as an installed package, not a fork.

Quick Start

1. Clone and install

git clone https://github.com/vaur94/mcp-code.git
cd mcp-code
npm ci
npm run build

2. Create a config file

Use examples/mcp-code.config.json as the starting point.

{
  "server": {
    "name": "mcp-code",
    "version": "0.2.0"
  },
  "logging": {
    "level": "info",
    "includeTimestamp": false
  },
  "workspace": {
    "rootPath": "/absolute/path/to/repository",
    "include": [
      "src/**/*.{ts,tsx,js,jsx,mts,cts,mjs,cjs}",
      "tests/**/*.{ts,tsx,js,jsx,mts,cts,mjs,cjs}"
    ],
    "exclude": [
      "**/node_modules/**",
      "**/dist/**",
      "**/build/**",
      "**/coverage/**",
      "**/.git/**"
    ]
  },
  "memory": {
    "maxSlices": 100,
    "maxPlans": 100,
    "maxVerificationReports": 100
  },
  "safety": {
    "maxSliceFiles": 12,
    "maxRelatedSymbols": 30,
    "maxEditsPerPlan": 20
  },
  "verification": {
    "executeByDefault": true,
    "scripts": {
      "typecheck": "typecheck",
      "lint": "lint",
      "test": "test"
    },
    "maxOutputChars": 4000
  },
  "security": {
    "commands": {
      "allowed": ["npm"]
    },
    "paths": {
      "allowed": ["/absolute/path/to/repository"]
    }
  }
}

3. Point your MCP host to the built server

{
  "mcpServers": {
    "mcp-code": {
      "command": "node",
      "args": ["/absolute/path/to/mcp-code/dist/index.js"],
      "env": {
        "MCP_CODE_CONFIG": "/absolute/path/to/mcp-code.config.json"
      }
    }
  }
}

4. Start with the semantic workflow

1. Call resolve_code_slice.
2. Call explain_slice.
3. Call plan_safe_edit.
4. Apply approved edits with apply_safe_edit.
5. Inspect downstream impact with analyze_impact.
6. Validate the touched scope with verify_slice.

Tool Surface

Tool	Purpose
resolve_code_slice	Resolve the smallest useful semantic working set for a symbol, file, or coding target.
explain_slice	Compress a slice into responsibilities, constraints, contracts, and risks.
plan_safe_edit	Create a bounded edit plan with invariants, touched files, and verification guidance.
apply_safe_edit	Apply approved edits only within the planned symbol and file scope.
analyze_impact	Estimate blast radius, downstream dependents, and contract exposure.
verify_slice	Route targeted validation and group failures by touched-scope relevance.

Architecture Snapshot

• src/index.ts boots the server through @vaur94/mcpbase.
• src/context/ builds the shared service container and typed execution context.
• src/infrastructure/repository-analyzer.ts owns slice resolution, explanation, edit planning, impact analysis, and bounded mutation.
• src/infrastructure/verification-runner.ts maps slice scope to repository verification commands.
• src/tools/ exposes the fixed six-tool public surface.

Documentation

• Docs hub: docs/README.md
• English index: docs/en/index.md
• Turkish index: docs/tr/index.md
• Getting started: docs/en/user-guide/getting-started.md
• Configuration: docs/en/user-guide/configuration.md
• OpenCode integration: docs/en/integration/opencode.md
• Architecture overview: docs/en/architecture/overview.md
• Tool reference: docs/en/api/tool-reference.md

Development

npm ci
npm run lint
npm run typecheck
npm run test
npm run test:protocol
npm run build
npm run ci:check

Release Status

• GitHub release automation is active on main.
• release-please opens or refreshes a release PR from conventional commits, then creates the GitHub release when that PR is merged.
• The publish target is @vaur94/mcp-code.
• If @vaur94/mcp-code has not been published before, do the first npm publish manually from the package root before attaching trusted publishing in publish.yml.
• .github/workflows/publish.yml verifies the package with npm run ci:check and npm run pack:dry-run before any publish step.
• Real npm publish runs from the published release event and checks that the GitHub tag matches package.json.
• If you want CI to run automatically on release PRs, add an optional RELEASE_PLEASE_TOKEN secret backed by a GitHub personal access token.

Repository Layout

mcp-code/
├── src/                 # Runtime entry, services, schemas, and tool adapters
├── tests/               # Unit, integration, protocol, and fixtures
├── docs/                # English and Turkish product and developer docs
├── examples/            # Ready-to-copy config and host integration examples
├── .github/             # CI, release, issue, PR, and hygiene automation
└── AGENTS.md            # AI-agent-oriented repository knowledge base

Contributing

Contributions are welcome. Start with CONTRIBUTING.md, run npm run ci:check, and keep changes aligned with the semantic workflow boundary.

Security and Support

• Security policy: SECURITY.md
• Support guide: SUPPORT.md
• Release details: RELEASE.md

License

MIT. See LICENSE.

Last updated: 2026-03-10