chore: everything the registries and first-time visitors ask for (#13)

The official MCP Registry was unreachable: it proves ownership by fetching the
published package and matching an `mcpName` field against the server name, and
neither that field nor server.json existed. Both are here now, and server.json
validates against the registry schema rather than against my reading of it.

server.json repeats the version twice, which is the same problem the plugin
manifests had. Both copies are placeholders and the release workflow stamps
them from the tag alongside package.json, so there is still no version written
down anywhere and still no release commit. A test pins both placeholders and
checks that `mcpName`, the server name and the package identifier agree, since
a mismatch only surfaces at publish time, after npm has already accepted the
release.

Publishing to the registry now hangs off the same tag as the npm publish,
authenticated by the same OIDC token, so no secret is added. It retries: npm
accepts a publish before the package is queryable, and the registry validates
by fetching it.

`--version` did not exist. It is the first thing a bug report needs, so the
issue template asked for something that could not be produced. It answers
before the configuration is read, which is the state a machine reporting a bug
is usually in.

SECURITY.md, CONTRIBUTING.md and an issue template, because people arriving
from a directory land on a repository that can reconfigure their network and
should be able to see how the password is stored and what happens to it. The
issue template asks for model and firmware first: nearly every difference in
this project comes down to one of those two.

CONTRIBUTING says the thing that actually matters here rather than the usual
formalities: verify against the router, not against your model of it, and name
the model and version you checked on. It also answers the vendor-adapter
question ahead of time, so nobody writes one before asking.

Author: salatmaster

.github/ISSUE_TEMPLATE/bug_report.yml

@@ -0,0 +1,49 @@
+name: Bug report
+description: Something behaves differently from what the documentation says
+labels: [bug]
+body:
+  - type: markdown
+    attributes:
+      value: |
+        Please do not paste real MAC addresses, private IP addresses, SSIDs or
+        keys. Replace them with placeholders.
+
+  - type: input
+    id: model
+    attributes:
+      label: Router model and KeeneticOS version
+      description: >-
+        From `get_system_info`, or the bottom of the router. Almost every
+        difference in this project comes down to one of these two, so a report
+        without them usually cannot be acted on.
+      placeholder: Keenetic Ultra (KN-1811), KeeneticOS 5.1.3
+    validations:
+      required: true
+
+  - type: textarea
+    id: what
+    attributes:
+      label: What happened
+      description: >-
+        The tool you called, what it returned, and what you expected instead.
+        If a change reported success but did not take effect, say so plainly:
+        the router accepts some wrong commands silently, and that is the failure
+        this project cares about most.
+    validations:
+      required: true
+
+  - type: textarea
+    id: reproduce
+    attributes:
+      label: How to reproduce
+      placeholder: |
+        1. list_devices { "filter": "active" }
+        2. update_device { "mac": "02:00:00:00:00:01", "access": "deny" }
+        3. The response says applied, the device stays online
+
+  - type: input
+    id: version
+    attributes:
+      label: keenetic-mcp version
+      description: "`npx keenetic-mcp --version`"
+      placeholder: "0.3.0"

.github/ISSUE_TEMPLATE/config.yml

@@ -0,0 +1,10 @@
+blank_issues_enabled: true
+contact_links:
+  - name: Design question, or another router vendor
+    url: https://github.com/salatmaster/keenetic-mcp/issues/new
+    about: >-
+      Open a blank issue. Questions about where a boundary should sit, or
+      whether a change would be taken, are welcome before any code is written.
+  - name: Something with security implications
+    url: https://github.com/salatmaster/keenetic-mcp/security/advisories/new
+    about: Report privately rather than in a public issue.

.github/workflows/release.yml

@@ -47,6 +47,11 @@ jobs:
             exit 1
           fi
           npm version "$version" --no-git-tag-version
+          # server.json repeats the version twice and the MCP registry rejects a
+          # value that disagrees with the published package, so it is stamped
+          # from the same tag rather than kept in step by hand.
+          jq --arg v "$version" '.version = $v | .packages[0].version = $v' \
+            server.json > server.tmp && mv server.tmp server.json
           echo "publishing $(node -p 'require("./package.json").version')"
 
       # Provenance ties the tarball to this workflow run, so anyone can verify it
@@ -56,3 +61,23 @@ jobs:
       # ENEEDAUTH rather than a clear message. Check that the publisher on npm
       # names this repository and this workflow filename exactly.
       - run: npm publish --provenance --access public
+
+      # The registry indexes metadata only, and proves ownership by fetching the
+      # published package and matching its `mcpName` against the server name. So
+      # it has to run after npm, and it retries: npm accepts the publish before
+      # the package is queryable, and the first attempt can lose that race.
+      #
+      # Authenticated by the same OIDC token as the npm publish above, so there
+      # is still no secret stored anywhere.
+      - name: Publish to the MCP Registry
+        run: |
+          curl -L "https://github.com/modelcontextprotocol/registry/releases/latest/download/mcp-publisher_$(uname -s | tr '[:upper:]' '[:lower:]')_$(uname -m | sed 's/x86_64/amd64/;s/aarch64/arm64/').tar.gz" \
+            | tar xz mcp-publisher
+          ./mcp-publisher login github-oidc
+          for attempt in 1 2 3 4; do
+            if ./mcp-publisher publish; then exit 0; fi
+            echo "attempt $attempt failed, waiting for npm to catch up"
+            sleep 20
+          done
+          echo "the package is on npm but the registry would not take it"
+          exit 1

CONTRIBUTING.md

@@ -0,0 +1,64 @@
+# Contributing
+
+Bug reports and pull requests are welcome. Two external contributions have
+already landed, so this is not a formality.
+
+## Running it
+
+```
+npm install
+npm test          # no router required
+npm run typecheck
+npm run build
+```
+
+Tests run against sanitized fixtures captured from a real router. To refresh
+them, or to run a read-only smoke test against your own:
+
+```
+KEENETIC_HOST=… KEENETIC_PASSWORD=… npm run capture:fixtures
+KEENETIC_TEST_HOST=… KEENETIC_TEST_PASSWORD=… npm run smoke
+```
+
+## The one thing that matters most
+
+**Verify against the router, not against your model of it.**
+
+Keenetic answers a wrong field name with `{}`, HTTP 200, no error, and nothing
+changed. It is indistinguishable from success. Two real bugs here passed every
+unit test and only surfaced against live hardware, because the tests asserted
+what the author assumed the router does.
+
+So: read every write back through whichever view actually exposes the field, and
+say in the pull request which model and KeeneticOS version you checked it on.
+`src/tools/write.ts` is the pattern. `docs/rci-api.md` collects the traps.
+
+If a change cannot be verified without hardware you do not have, say so. That is
+a normal answer here and better than a confident guess.
+
+## Never commit real network data
+
+A test scans the whole repository for anything shaped like a real MAC address, a
+private IP or key material, and it will fail your build. It exists because those
+have leaked here before, including from a fixture captured off a live router.
+
+Device names and SSIDs have no detectable shape, so nothing catches those.
+Read your own diff before pushing it.
+
+## Style
+
+Match the surrounding code. Comments explain why something is the way it is,
+especially when it looks wrong: most of them are load-bearing and record a trap
+that cost someone an afternoon.
+
+Plain ASCII hyphens, no em dashes, anywhere.
+
+Commit messages say what changed and why it had to change that way.
+
+## Adding another vendor
+
+Please open an issue first. The code is RCI-shaped throughout, and a vendor
+boundary with one implementation behind it would be a guess. A separate
+repository that borrows the tool shapes, the verified-write pattern and the
+skills format is the cheaper start, and the parts worth sharing can be extracted
+once there are two working servers to compare.

README.md

@@ -163,6 +163,9 @@ different manifests but share the same skills and the same server definition.
 - **LAN only.** No cloud, no telemetry, no outbound connection to anything but
   your router.
 
+Where the password is stored on each platform, and how to report something
+privately, are in [SECURITY.md](SECURITY.md).
+
 ## Supported routers
 
 RCI, the API this uses, is a standard part of KeeneticOS rather than a feature

SECURITY.md

@@ -0,0 +1,41 @@
+# Security
+
+## What this software can reach
+
+It authenticates to a router as an administrator and can change its
+configuration. That is the point of it, and it is also the whole risk: anything
+that can talk to this server can reconfigure the network it runs on.
+
+## Where the password goes
+
+The setup wizard stores the router password in the operating system keychain -
+Keychain Services on macOS, Credential Manager on Windows, Secret Service on
+Linux. If no keychain is available it falls back to a file with mode `0600` and
+says so rather than pretending otherwise.
+
+The password is never written to a settings file, never included in a tool
+response, and never logged. `KEENETIC_HOST`, `KEENETIC_USER` and
+`KEENETIC_PASSWORD` override the stored values, which is what a container wants.
+
+## What it does not do
+
+No cloud, no telemetry, no outbound connection to anything but your router. It
+runs on your machine and speaks to the router over your LAN.
+
+## Reducing what it can do
+
+`--read-only` does not register the write tools at all, rather than registering
+them and refusing, so an agent never sees them.
+
+Changes apply to the running configuration and are discarded on reboot until
+`save_config` is called, which nothing does on its own.
+
+## Reporting something
+
+Open a [security advisory](https://github.com/salatmaster/keenetic-mcp/security/advisories/new)
+rather than a public issue, and give the model and KeeneticOS version. Expect a
+first reply within a week.
+
+Please do not include real MAC addresses, private IP addresses, SSIDs or keys in
+a report. A test in this repository scans every file for them precisely because
+they are easy to paste in by accident.

package.json

@@ -1,6 +1,7 @@
 {
   "name": "keenetic-mcp",
   "version": "0.0.0-dev",
+  "mcpName": "io.github.salatmaster/keenetic-mcp",
   "description": "Control your Keenetic router from Claude, Codex, Cursor, or any MCP agent",
   "type": "module",
   "license": "MIT",

server.json

@@ -0,0 +1,43 @@
+{
+  "$schema": "https://static.modelcontextprotocol.io/schemas/2025-12-11/server.schema.json",
+  "name": "io.github.salatmaster/keenetic-mcp",
+  "description": "Control a Keenetic router: devices, Wi-Fi, VPN routing, segments, safe verified writes.",
+  "repository": {
+    "url": "https://github.com/salatmaster/keenetic-mcp",
+    "source": "github"
+  },
+  "version": "0.0.0-dev",
+  "packages": [
+    {
+      "registryType": "npm",
+      "identifier": "keenetic-mcp",
+      "version": "0.0.0-dev",
+      "transport": {
+        "type": "stdio"
+      },
+      "environmentVariables": [
+        {
+          "name": "KEENETIC_HOST",
+          "description": "Router address on the LAN, for example 192.168.1.1. Optional: `npx keenetic-mcp init` discovers it from the default gateway and stores it.",
+          "isRequired": false,
+          "isSecret": false,
+          "format": "string"
+        },
+        {
+          "name": "KEENETIC_USER",
+          "description": "Router login. Optional, defaults to admin.",
+          "isRequired": false,
+          "isSecret": false,
+          "format": "string"
+        },
+        {
+          "name": "KEENETIC_PASSWORD",
+          "description": "Router password. Optional: the setup wizard stores it in the operating system keychain instead. Use this in a container, where there is no keychain.",
+          "isRequired": false,
+          "isSecret": true,
+          "format": "string"
+        }
+      ]
+    }
+  ]
+}

src/index.ts

@@ -36,6 +36,13 @@ async function main(): Promise<void> {
   // credentials in .env instead of exporting them. A no-op once installed.
   loadLocalEnv();
 
+  // Before the config is read, so it answers on a machine that has never been
+  // set up. Every bug report starts by asking which version is running.
+  if (process.argv.includes('--version') || process.argv.includes('-v')) {
+    process.stdout.write(`${resolveVersion()}\n`);
+    return;
+  }
+
   // `init` is a subcommand rather than a second binary, so the published
   // surface stays a single command.
   if (process.argv[2] === 'init') {

tests/binary.test.ts

@@ -24,9 +24,14 @@ interface RunResult {
   stderr: string;
 }
 
-function run(entry: string, stdin: string, env: NodeJS.ProcessEnv): Promise<RunResult> {
+function run(
+  entry: string,
+  stdin: string,
+  env: NodeJS.ProcessEnv,
+  args: string[] = []
+): Promise<RunResult> {
   return new Promise(resolve => {
-    const child = spawn(process.execPath, [entry], { env });
+    const child = spawn(process.execPath, [entry, ...args], { env });
     let stdout = '';
     let stderr = '';
     child.stdout.on('data', chunk => {
@@ -102,6 +107,21 @@ describe('the built binary', () => {
     expect(response.result?.serverInfo?.version).toBe('9.9.9-probe');
   });
 
+  // Answered before the configuration is read, so it works on a machine that
+  // has never run the wizard. That is the machine a bug report comes from.
+  it('prints its version and exits, with no router configured', async () => {
+    const result = await run(DIST, '', { KEENETIC_MCP_VERSION: '' }, ['--version']);
+
+    expect(result.code).toBe(0);
+    expect(result.stdout.trim()).toBe(
+      (
+        JSON.parse(await readFile(new URL('../package.json', import.meta.url), 'utf8')) as {
+          version: string;
+        }
+      ).version
+    );
+  });
+
   // Regression: npm installs a bin as a symlink in node_modules/.bin, so under
   // npx the entry path is the link and the module path is its target. Version
   // 0.1.0 compared them unresolved, matched nothing, and exited silently.