Package a Claude Code plugin with a skill, subagent, and local MCP server

{
  "name": "safe-repository-review-plugin",
  "version": "1.0.0",
  "private": true,
  "type": "module",
  "scripts": {
    "test:contract": "node test/plugin-contract.mjs ../..",
    "test:mcp": "node mcp/repository-policy.mjs --self-test"
  },
  "dependencies": {
    "@modelcontextprotocol/server": "2.0.0",
    "zod": "4.4.3"
  }
}

{
  "$schema": "https://json.schemastore.org/claude-code-plugin-manifest.json",
  "name": "safe-repository-review",
  "displayName": "Safe Repository Review",
  "version": "1.0.0",
  "description": "Manual, read-only repository review with a scoped agent and local policy lookup tool.",
  "author": {
    "name": "Platform Engineering"
  },
  "license": "MIT",
  "keywords": [
    "repository-review",
    "read-only",
    "mcp",
    "skill",
    "subagent"
  ],
  "defaultEnabled": false
}

import assert from "node:assert/strict";
import { fileURLToPath } from "node:url";
import { McpServer } from "@modelcontextprotocol/server";
import { serveStdio } from "@modelcontextprotocol/server/stdio";
import * as z from "zod/v4";

const POLICIES = Object.freeze({
  boundaries: [
    "Read only files inside the repository root.",
    "Never request, read, print, or summarize secrets.",
    "Do not edit files, run shell commands, or call network tools."
  ],
  evidence: [
    "Cite repository-relative paths and line numbers.",
    "Separate observed facts from inferences.",
    "Report uncertainty and missing evidence explicitly."
  ],
  escalation: [
    "Stop when evidence requires a protected path or external system.",
    "Ask the operator to collect approved evidence instead of widening access.",
    "Treat MCP annotations as hints, not an authorization boundary."
  ]
});

export function policyFor(topic) {
  if (!Object.hasOwn(POLICIES, topic)) {
    throw new Error("unsupported policy topic");
  }
  return POLICIES[topic].join("\n");
}

export function createServer() {
  const server = new McpServer(
    { name: "repository-policy", version: "1.0.0" },
    {
      instructions:
        "This server returns static review policy. It does not read files, use the network, or mutate state."
    }
  );

  server.registerTool(
    "repository_policy",
    {
      title: "Repository review policy",
      description:
        "Return one reviewed policy section for a read-only repository review.",
      inputSchema: z.object({
        topic: z.enum(["boundaries", "evidence", "escalation"])
      }),
      annotations: {
        readOnlyHint: true,
        destructiveHint: false,
        idempotentHint: true,
        openWorldHint: false
      }
    },
    async ({ topic }) => ({
      content: [{ type: "text", text: policyFor(topic) }]
    })
  );

  return server;
}

const isMain = process.argv[1] === fileURLToPath(import.meta.url);
if (isMain && process.argv.includes("--self-test")) {
  assert.match(policyFor("boundaries"), /Read only files/);
  assert.match(policyFor("evidence"), /line numbers/);
  assert.throws(() => policyFor("unknown"));
  console.log("MCP_POLICY_OK topics=3 network=none writes=none");
} else if (isMain) {
  console.error("repository-policy MCP server running on stdio");
  void serveStdio(createServer);
}

{
  "mcpServers": {
    "repository-policy": {
      "command": "node",
      "args": [
        "${CLAUDE_PLUGIN_ROOT}/mcp/repository-policy.mjs"
      ]
    }
  }
}

---
name: repository-review
description: Perform a manual, read-only review of repository code or configuration and return path-and-line evidence. Use only when the user explicitly asks for a repository review.
argument-hint: "[path-or-question]"
disable-model-invocation: true
---

Review $ARGUMENTS without changing the repository.

1. Confirm the requested scope and exclusions.
2. In the main conversation, inspect `/mcp` and call the plugin's
   `repository_policy` tool for `boundaries`, `evidence`, and
   `escalation`. Stop if the server is not connected or approval was denied.
3. Delegate the scoped inspection to
   `safe-repository-review:read-only-reviewer`.
4. Require repository-relative paths and line numbers for every finding.
5. Separate facts, inferences, unknowns, and suggested follow-up.
6. Do not edit files, execute commands, browse the network, or request secrets.
7. Return "No supported finding" when the available evidence does not support
   a concrete issue.

The MCP tool's read-only annotation is a client hint, not enforcement. The
agent's `tools` allowlist is the operative reduction for the delegated review.

---
name: read-only-reviewer
description: Inspect a user-approved repository scope and report evidence-backed correctness, reliability, or security concerns without editing files or running commands.
tools: Read, Glob, Grep
model: sonnet
effort: medium
maxTurns: 12
background: false
---

You are a read-only repository reviewer.

Boundaries:
- Stay inside the scope named in the delegation message.
- Never read common secret files, credential directories, generated key
  material, or paths outside the repository.
- Do not ask for Bash, PowerShell, Write, Edit, WebFetch, WebSearch, Agent, or
  MCP tools.
- Do not treat absence of evidence as proof of safety.

Method:
1. Restate scope and exclusions.
2. Locate only files needed for the stated question.
3. Read the smallest useful ranges.
4. For each candidate, cite a repository-relative path and line number,
   describe the observed behavior, and explain the concrete impact.
5. Reject speculative candidates that lack a traceable source-to-effect path.
6. Finish with findings ordered by severity, then unknowns and safe follow-up.

Do not modify the repository. If the evidence requires an unavailable tool,
protected file, external service, or runtime execution, stop and state exactly
what an authorized operator must collect.

{
  "$schema": "https://json.schemastore.org/claude-code-marketplace.json",
  "name": "company-tools",
  "owner": {
    "name": "Platform Engineering"
  },
  "description": "Reviewed Claude Code extensions for internal engineering work.",
  "version": "1.0.0",
  "plugins": [
    {
      "name": "safe-repository-review",
      "source": "./plugins/safe-repository-review",
      "description": "Manual read-only repository review with explicit evidence boundaries.",
      "version": "1.0.0",
      "category": "development",
      "tags": [
        "review",
        "read-only",
        "mcp"
      ]
    }
  ]
}

import assert from "node:assert/strict";
import fs from "node:fs";
import path from "node:path";
import { policyFor } from "../mcp/repository-policy.mjs";

const marketplaceRoot = path.resolve(process.argv[2] ?? ".");
const pluginRoot = path.join(
  marketplaceRoot,
  "plugins",
  "safe-repository-review"
);

const read = (relative) =>
  fs.readFileSync(path.join(pluginRoot, relative), "utf8");
const json = (relative) => JSON.parse(read(relative));

const marketplace = JSON.parse(
  fs.readFileSync(
    path.join(marketplaceRoot, ".claude-plugin", "marketplace.json"),
    "utf8"
  )
);
assert.equal(marketplace.name, "company-tools");
assert.equal(marketplace.plugins.length, 1);
assert.equal(
  marketplace.plugins[0].source,
  "./plugins/safe-repository-review"
);

const manifest = json(".claude-plugin/plugin.json");
assert.equal(manifest.name, "safe-repository-review");
assert.equal(manifest.version, "1.0.0");
assert.equal(manifest.defaultEnabled, false);

const skill = read("skills/repository-review/SKILL.md");
assert.match(skill, /disable-model-invocation: true/);
assert.match(skill, /safe-repository-review:read-only-reviewer/);
assert.match(skill, /Do not edit files/);

const agent = read("agents/read-only-reviewer.md");
assert.match(agent, /tools: Read, Glob, Grep/);
for (const unsupported of ["hooks:", "mcpServers:", "permissionMode:"]) {
  assert.equal(
    agent.includes(unsupported),
    false,
    "plugin agent contains unsupported field: " + unsupported
  );
}

const mcp = json(".mcp.json");
const server = mcp.mcpServers["repository-policy"];
assert.equal(server.command, "node");
assert.deepEqual(server.args, [
  "${CLAUDE_PLUGIN_ROOT}/mcp/repository-policy.mjs"
]);
assert.equal(server.env, undefined);

const packageJson = json("package.json");
assert.equal(packageJson.dependencies["@modelcontextprotocol/server"], "2.0.0");
assert.equal(packageJson.dependencies.zod, "4.4.3");
assert.match(policyFor("escalation"), /annotations as hints/);

console.log(
  "PLUGIN_CONTRACT_OK marketplace=1 plugin=1 skill=manual agent=read-only " +
  "mcp=local secrets=none"
);