MCP Server v2 Production Pack

Summary

The linter found 3 errors and 5 warnings: two missing hints OpenAI requires, a shell-injection parameter, a generic executor and a read-only hint on a tool that can run git push. The agent replaced it with one tool per operation and the rerun is clean.

Linter, before

$ node lint-mcp-server.mjs -- node dist/server.js
server: repo-tools 1.0.0  protocol: 2025-11-25 (legacy)  tools: 1
ERROR run  risky-shell-param  Parameter "command" looks like free-form shell or code input.
ERROR run  hint-missing       destructiveHint is not set; OpenAI plugin review requires an explicit boolean.
ERROR run  hint-missing       openWorldHint is not set; OpenAI plugin review requires an explicit boolean.
WARN  run  generic-executor   Generic executor name. Expose each operation as its own tool.
WARN  run  description-weak   Description is 2 word(s).
WARN  run  param-undocumented Parameters without a description: command.
WARN  run  hint-missing       idempotentHint is not set.
WARN  run  hint-mismatch      Name starts with a write verb but readOnlyHint=true.
3 error(s), 5 warning(s), 2 note(s)

Fixed tool

const run = promisify(execFile);

server.registerTool(
  'git_log',
  {
    title: 'Git log',
    description: 'List the latest commits on one branch of the configured repository. Returns up to 20 one-line entries. Read-only.',
    inputSchema: z.object({
      branch: z.string().regex(/^[A-Za-z0-9._\/-]{1,100}$/).describe('Branch name, for example main'),
      limit: z.number().int().min(1).max(20).default(10).describe('Number of commits to return')
    }),
    annotations: { readOnlyHint: true, destructiveHint: false, idempotentHint: true, openWorldHint: false }
  },
  async ({ branch, limit }) => {
    if (branch.startsWith('-')) return { content: [{ type: 'text', text: 'Branch names cannot start with "-".' }], isError: true };
    try {
      const { stdout } = await run('git', ['log', '--oneline', '-n', String(limit), branch, '--'], { timeout: 10_000, maxBuffer: 1_000_000 });
      return { content: [{ type: 'text', text: stdout || 'No commits.' }] };
    } catch {
      return { content: [{ type: 'text', text: `Unknown branch "${branch}". Call git_branches to list branches.` }], isError: true };
    }
  }
);

Linter, after

server: repo-tools 1.1.0  protocol: 2025-11-25 (legacy)  tools: 1
INFO  git_log  output-schema-missing  No outputSchema. Add one and return structuredContent when callers need typed results.
0 error(s), 0 warning(s), 1 note(s)

Both servers were built against @modelcontextprotocol/server 2.3.1 and this is the linter's real output.

Next steps

• Add git_branches the same way and server instructions.
• Add the contract test from mcp-testing so CI fails if any tool loses a hint.