@vaur94/mcp-code

mcp-code

🇬🇧 English | 🇹🇷 Turkce

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.1.0"
  },
  "logging": {
    "level": "info",
    "includeTimestamp": false
  },
  "workspace": {
    "rootPath": "/absolute/path/to/repository",
    "include": ["src/**/*.{ts,tsx,js,jsx}", "tests/**/*.{ts,tsx,js,jsx}"],
    "exclude": ["**/node_modules/**", "**/dist/**", "**/coverage/**"]
  },
  "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

• Call resolve_code_slice
• Call explain_slice
• Call plan_safe_edit
• Apply approved edits with apply_safe_edit
• Inspect downstream impact with analyze_impact
• 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, explanations, edit planning, impact analysis, and guarded mutation.
• src/infrastructure/verification-runner.ts maps slice scope to repo verification commands.
• src/tools/ exposes the fixed six-tool public surface.

Documentation

• 📘 Docs hub: docs/README.md
• 🇬🇧 English docs: docs/en/README.md
• 🇹🇷 Turkish docs: docs/tr/README.md
• 🧭 Getting started: docs/en/user-guide/getting-started.md
• ⚙️ Configuration: docs/en/user-guide/configuration.md
• 🔌 Host integration: docs/en/integration/opencode.md
• 🏛️ Architecture: 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; the unscoped mcp-code package is owned by another maintainer and cannot be trusted or published from this repo.
• The first publish for @vaur94/mcp-code still needs one manual npm publish, then trusted publishing can take over with GitHub OIDC.
• .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 PAT.

Repository Layout

mcp-code/
├── src/                 # Runtime entry, services, schemas, and tool adapters
├── tests/               # Unit, integration, protocol, and fixtures
├── docs/                # English + 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.

License

MIT. See LICENSE.