# codeforge-mcp

**CodeForge** — an MCP (Model Context Protocol) server that exposes Senior Software Engineer / Technical Lead capabilities as individual tools. Any MCP-compatible client — Claude Desktop, Cursor, VS Code, Claude Code — can call these tools to delegate engineering tasks to a model playing a senior-engineer persona.

The server is **prompt-mediated** for reasoning tools: code generation, code review, RCA, etc. each return a structured prompt that locks the host LLM into the senior-engineer persona and a strict output schema. The reasoning happens in the client's LLM, so no second LLM API key is needed.

Jira tools call the Jira REST API directly.

---

## Tools exposed

| Tool | Purpose |
| --- | --- |
| `generate_code` | Generate clean, scalable, production-ready code with tests, logging, and docs. |
| `scaffold_service` | Scaffold a new Comviva Spring Boot microservice (pom, packaging, logging, Kafka, Consul, OpenAPI) per the standards in [`standards/comviva-springboot.md`](standards/comviva-springboot.md). |
| `generate_test_cases` | Generate a JUnit 5 + Mockito test class for one Java class with `@DisplayName` on every test, `@Nested` groups per method, AssertJ assertions, and Comviva copyright header. For project-wide tests, the host LLM iterates over source files and calls this per class. |
| `review_code` | Review a pull request / diff with severity-tagged findings anchored to file:line. |
| `analyze_bug` | Root-cause a bug from symptoms, stack trace, logs, and source. |
| `generate_rca` | Produce a publish-ready Root Cause Analysis report for an incident. |
| `jira_get_issue` | Fetch a Jira issue. |
| `jira_search_issues` | JQL search. |
| `jira_create_issue` | File a new issue (bug, story, task, epic). |
| `jira_update_issue` | Update fields on an issue. |
| `jira_transition_issue` | Move an issue through workflow states. |
| `jira_add_comment` | Attach investigation notes, RCA, or implementation updates. |
| `jira_link_issues` | Link related issues (Blocks, Relates, Caused by, etc.). |
| `jira_add_remote_link` | Attach a PR / deployment / dashboard URL to an issue. |
| `recommend_architecture` | Propose a scalable system design for a goal. |
| `review_architecture` | Review an API / database / microservice / pipeline / cloud infra design. |
| `identify_tech_debt` | Inventory technical debt and produce a refactor roadmap. |
| `review_cicd_pipeline` | Validate a CI/CD pipeline config. |
| `review_infra_config` | Review Kubernetes / Docker / Terraform / Helm / CloudFormation. |
| `deployment_readiness_check` | Pre-deploy go/no-go review with rollback and observability checks. |
| `generate_documentation` | Tech design, API reference, runbook, README, or module overview. |
| `generate_adr` | Architecture Decision Record (MADR style). |
| `generate_implementation_plan` | Phased implementation plan with risks and definition of done. |
| `generate_migration_strategy` | Migration strategy with stages, cutover, and rollback. |

---

## Install & build

```bash
cd D:/eclipse-workspace/MRTM_7.12/mrtm/codeforge-mcp
npm install
npm run build
```

This produces `dist/index.js`.

---

## Configure environment

Jira tools require credentials. Copy `.env.example` to `.env` and fill in:

```
JIRA_HOST=https://your-company.atlassian.net
JIRA_EMAIL=you@company.com
JIRA_API_TOKEN=<API token from id.atlassian.com/manage-profile/security/api-tokens>
JIRA_DEFAULT_PROJECT=MRTM
```

`.env` is **not** loaded automatically — pass these as real environment variables when the MCP client launches the server (see the next section). Tools that don't touch Jira work without these variables.

---

## Register with an MCP client

### Claude Desktop

Edit `%APPDATA%\Claude\claude_desktop_config.json` (Windows) and add:

```json
{
  "mcpServers": {
    "codeforge": {
      "command": "node",
      "args": ["D:/eclipse-workspace/MRTM_7.12/mrtm/codeforge-mcp/dist/index.js"],
      "env": {
        "JIRA_HOST": "https://your-company.atlassian.net",
        "JIRA_EMAIL": "you@company.com",
        "JIRA_API_TOKEN": "<token>",
        "JIRA_DEFAULT_PROJECT": "MRTM"
      }
    }
  }
}
```

Restart Claude Desktop. The tools will appear in the tool picker.

### Claude Code (CLI)

```bash
claude mcp add codeforge node "D:/eclipse-workspace/MRTM_7.12/mrtm/codeforge-mcp/dist/index.js" \
  -e JIRA_HOST=https://your-company.atlassian.net \
  -e JIRA_EMAIL=you@company.com \
  -e JIRA_API_TOKEN=... \
  -e JIRA_DEFAULT_PROJECT=MRTM
```

### Cursor / VS Code (with MCP extension)

Add an entry in the client's MCP settings pointing to the same `node dist/index.js` command with the env vars above.

---

## Company standards (used by `scaffold_service`)

The conventions for new microservices live in [`standards/comviva-springboot.md`](standards/comviva-springboot.md) — packaging, copyright header, constructor injection, `@Slf4j` parameterized logging, Spring Kafka config pattern, Consul config layout, error handling, JPA, scheduling, Dockerfile. Edit that file to refine conventions; `scaffold_service` re-reads it on every call (no rebuild needed).

### Example invocation from Claude

> Scaffold a new service called `rewardservice` that consumes the `reward.events` Kafka topic, persists a `RewardLedger` entity to MySQL, and exposes `GET /rewards/{customerId}` to read balances.

The MCP client picks `scaffold_service`, fills in the args, and the host LLM produces the full project — pom.xml, `RewardserviceApplication.java`, `config/KafkaConfig.java`, `service/RewardEventConsumer.java`, `dao/RewardLedgerRepository.java`, `model/RewardLedger.java`, `controller/RewardController.java`, `application.yml`, `bootstrap.yml`, `consul-prop.yml`, `logback-spring.xml`, `Dockerfile`, and tests — all carrying the Comviva copyright header and following every rule in the standards file.

---

## How the prompt-only tools work

When you call `review_code`, the server doesn't itself invoke an LLM. It returns a single text block containing:

1. A senior-engineer **persona** prelude (role, tone, standards).
2. The supplied inputs (the diff, PR title, etc.) embedded in a task description.
3. A strict **output contract** — the exact sections, severity scale, table columns, and rules the LLM must follow.

The host LLM (Claude Desktop, Cursor, etc.) then executes that prompt as its next reasoning step. Because the contract is strict and the persona is consistent across tools, you get reproducible, high-quality output without standing up a second LLM endpoint.

If you later want the server to call an LLM itself (e.g. for batch jobs without a host UI), wire an Anthropic client into each tool's `handler` and post the existing prompt body to it. The current architecture is designed to make that swap trivial.

---

## Adding a new tool

1. Create `src/tools/yourTool.ts` exporting a `ToolDefinition`:

   ```ts
   import { z } from "zod";
   import { withPersona } from "../prompts/persona.js";
   import type { ToolDefinition } from "./types.js";

   const Schema = z.object({ /* inputs */ });

   export const yourTool: ToolDefinition = {
     name: "your_tool",
     description: "What it does, in one sentence.",
     inputSchema: Schema,
     handler: async (raw) => {
       const input = Schema.parse(raw);
       return { content: [{ type: "text", text: withPersona("...prompt body...") }] };
     },
   };
   ```

2. Register it in `src/tools/index.ts` under the right capability group.
3. `npm run build`. The client picks up the new tool on next restart.

---

## Sharing with the team

Two distribution paths — start with **A**, promote to **B** once the standards stabilise.

### A. Git clone

**Maintainer (one-time):** push this folder to GitHub.

**Each teammate (one-time):**

```bash
git clone https://github.com/ThakurAnketPratapSingh/codeforge-mcp.git
cd codeforge-mcp
setup.bat      # Windows
./setup.sh     # macOS / Linux / Git Bash
```

`setup.bat` / `setup.sh` installs deps, builds, and runs `claude mcp add codeforge ...` automatically. Teammates add their own Jira creds afterwards (re-register with `-e JIRA_*` flags — see the setup script output).

**Getting updates:**

```bash
git pull && setup.bat
```

Standards live in [standards/comviva-springboot.md](standards/comviva-springboot.md), versioned with the repo, so `git pull` is how new conventions reach every teammate.

### B. Public npm (npmjs.com)

The package is published to the public npm registry as `@anketpsingh/codeforge-mcp`. Anyone with Node.js installed can grab it — no token needed.

> ⚠️ **Public publication means `standards/comviva-springboot.md` is searchable on npmjs.com.** Make sure that's intended.

**Maintainer — one-time setup:**

1. Create a free account at https://www.npmjs.com/signup
2. Enable 2FA on the account (npm requires it for publishing).
3. Authenticate on this machine:
   ```bash
   npm login
   ```
   Enter username, password, email, and the OTP from your authenticator.

**Maintainer — each release:**

```bash
npm run release:patch   # 0.1.0 → 0.1.1, builds, publishes
npm run release:minor   # 0.1.0 → 0.2.0
npm run release:major   # 0.1.0 → 1.0.0
```

`prepublishOnly` rebuilds from clean automatically. Only `dist/`, `standards/`, `README.md`, and `.env.example` ship.

**Each teammate — one-time:**

```bash
npm install -g @anketpsingh/codeforge-mcp
claude mcp add codeforge codeforge-mcp
```

No `.npmrc` or token required — it's public.

**Getting updates:**

```bash
npm install -g @anketpsingh/codeforge-mcp@latest
```

### Per-user secrets (both paths)

Jira credentials are per-user. Each teammate adds their own via `claude mcp add ... -e JIRA_EMAIL=... -e JIRA_API_TOKEN=...` after the base install. Shared values (`JIRA_HOST`, `JIRA_DEFAULT_PROJECT`) go in the README so everyone copies them verbatim.

### Evolving the standards

`standards/comviva-springboot.md` is the single source of truth. To change a convention:

1. Edit the file
2. **Path A**: commit, push, teammates `git pull && setup.bat`
3. **Path B**: bump version, `npm run release:minor`, teammates `npm install -g @anketpsingh/codeforge-mcp@latest`

Standards changes are visible in `git log standards/` — useful when investigating "why does the generator do X now".

---

## Project layout

```
codeforge-mcp/
├── src/
│   ├── index.ts              # stdio entry point
│   ├── server.ts             # MCP server wiring
│   ├── prompts/persona.ts    # shared senior-engineer persona
│   ├── jira/client.ts        # Jira REST client (Cloud v3 / ADF)
│   └── tools/
│       ├── types.ts          # ToolDefinition shape, error helper
│       ├── index.ts          # tool registry
│       ├── codeGeneration.ts
│       ├── codeReview.ts
│       ├── bugAnalysis.ts
│       ├── rca.ts
│       ├── jira.ts
│       ├── architecture.ts
│       ├── devops.ts
│       └── documentation.ts
├── package.json
├── tsconfig.json
└── .env.example
```