mcpship 0.0.0-stage → 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Freeapp SRL
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -1,3 +1,62 @@
-# Temporary Holding Version
+# mcpship
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+Check a remote MCP server against the Claude connector directory rules, then publish it: npm, the official MCP Registry, a Claude Code plugin repo and the Claude connector directory. One step at a time, for people and for agents.
+
+## Quick start
+
+    npx mcpship init https://example.com/mcp   # writes publish.json; fill in the fields
+    MCPSHIP_TOKEN=<access token or API key> npx mcpship check
+    npx mcpship next                            # the next step, with the exact command
+
+## Commands
+
+| Command | What it does |
+| --- | --- |
+| `init <url>` | Writes a publish.json template in the current folder |
+| `check [url]` | Tests sign-in discovery, tools and listing; exit code 1 if a rule fails |
+| `packet` | Writes docs/directory/submission.md: the text for each directory form step |
+| `next` | The first unfinished step, with the command or click |
+| `status` | Live state of npm, the MCP Registry, the plugin repo and the directory |
+| `done directory` | Records that you submitted the directory form |
+| `mcp` | Runs as a local MCP server over stdio |
+
+Add `--json` for machine-readable output and `--dir <path>` to point at another folder.
+
+npm counts as published only when you are a maintainer of the package. mcpship asks `npm whoami`; if you publish with a token instead of `npm login`, set `channels.npm.maintainer` to your npm user name in publish.json.
+
+## What check tests
+
+| Rule | Fails when |
+| --- | --- |
+| auth.https | the server URL is not https |
+| auth.www-authenticate | an unauthenticated call does not return 401 with resource_metadata |
+| auth.resource-metadata | protected resource metadata is missing or has no authorization server |
+| auth.as-metadata | authorization server metadata is missing |
+| auth.pkce | S256 is not supported |
+| auth.client-registration | neither Dynamic Client Registration nor Client ID Metadata Documents |
+| tools.reachable | tools/list fails with the given token (skipped without one) |
+| tools.title | a tool has no title |
+| tools.annotations | a tool has neither readOnlyHint nor destructiveHint |
+| tools.instructions | a description tells the model what to do ("use it first", "you must", "call X") |
+| tools.hidden-text | a description holds invisible characters or encoded text |
+| listing.icon-url | the icon URL is not a public https PNG |
+| listing.pages | docs, privacy or terms page does not load |
+| listing.lengths | name, one-liner or description is over the form limit, or a field is empty |
+| listing.unpublished-mention | a page tells users to run `npx <package>` before it is on npm |
+
+Warnings: `tools.mentions` (a description names another tool) and `listing.em-dash`.
+
+## Use it from Claude Code
+
+    /plugin marketplace add emanueltns/mcpship
+    /plugin install mcpship@mcpship
+
+Then ask Claude to publish your MCP server. The plugin adds the mcpship tools and a skill that walks through each step.
+
+## Privacy
+
+mcpship runs on your machine. It calls your server, the URLs in your publish.json, the MCP Registry API, and whatever `npm` and `gh` call. It sends no telemetry. MCPSHIP_TOKEN is read from the environment and never printed.
+
+## License
+
+MIT

package/bin/mcpship.js

@@ -0,0 +1,82 @@
+#!/usr/bin/env node
+'use strict'
+const commands = require('../lib/commands')
+const { redact, formatCheck, formatStatus, formatNext } = require('../lib/format')
+const { version } = require('../package.json')
+
+const USAGE = `mcpship ${version}: check and publish a remote MCP server
+
+Usage:
+  mcpship init <server-url>      Write a publish.json template here
+  mcpship check [server-url]     Test the server against the Claude directory rules
+  mcpship packet                 Write docs/directory/submission.md (text for each form step)
+  mcpship next                   Show the next unfinished publishing step
+  mcpship status                 Show npm, MCP Registry, plugin and directory status
+  mcpship done directory         Record that you submitted the directory form
+  mcpship mcp                    Run as a local MCP server (stdio) for agents
+
+Options:
+  --json         Print JSON instead of text
+  --dir <path>   Folder with publish.json (default: current folder)
+
+Environment:
+  MCPSHIP_TOKEN  Access token or API key, used to list the server's tools. Never printed.`
+
+function parse(argv) {
+  const out = { cmd: argv[0], args: [], json: false, dir: process.cwd() }
+  for (let i = 1; i < argv.length; i++) {
+    if (argv[i] === '--json') out.json = true
+    else if (argv[i] === '--dir') out.dir = argv[++i]
+    else out.args.push(argv[i])
+  }
+  return out
+}
+
+async function main() {
+  const argv = process.argv.slice(2)
+  if (argv[0] === '--version' || argv[0] === '-v') return console.log(version)
+  if (!argv.length || argv[0] === '--help' || argv[0] === '-h' || argv[0] === 'help') return console.log(USAGE)
+  const { cmd, args, json, dir } = parse(argv)
+  const token = process.env.MCPSHIP_TOKEN || undefined
+  const print = (data, text) => console.log(redact(json ? JSON.stringify(data, null, 2) : text, token))
+  try {
+    switch (cmd) {
+      case 'init': {
+        const r = commands.init({ dir, url: args[0] })
+        return print(r, `Wrote ${r.path}. Fill in every empty field, then run mcpship check.`)
+      }
+      case 'check': {
+        const r = await commands.check({ dir, url: args[0], token })
+        print(r, formatCheck(r))
+        process.exitCode = r.summary.fail ? 1 : 0
+        return
+      }
+      case 'packet': {
+        const r = await commands.packet({ dir, token })
+        return print(r, `Wrote ${r.path}.${r.missing.length ? `\nMissing in publish.json: ${r.missing.join(', ')}` : ''}`)
+      }
+      case 'next': {
+        const r = await commands.next({ dir, token })
+        return print(r, formatNext(r))
+      }
+      case 'status': {
+        const r = await commands.status({ dir })
+        return print(r, formatStatus(r))
+      }
+      case 'done': {
+        const r = commands.done({ dir, channel: args[0] })
+        return print(r, `Recorded: ${r.channel} submitted on ${r.date}.`)
+      }
+      case 'mcp':
+        return require('../lib/mcp').serve(process.stdin, process.stdout, { token })
+      default:
+        console.error(USAGE)
+        process.exitCode = 2
+    }
+  } catch (e) {
+    console.error(redact(`mcpship: ${e.message}`, token))
+    process.exitCode = e instanceof commands.UsageError ? 2 : 1
+  }
+}
+
+main()

package/lib/channels.js

@@ -0,0 +1,96 @@
+'use strict'
+const fs = require('fs')
+const path = require('path')
+const { run } = require('./exec')
+const { request } = require('./http')
+
+const REGISTRY_API = 'https://registry.modelcontextprotocol.io/v0/servers'
+// The registry search took 31-45 s in October 2026 tests.
+const REGISTRY_TIMEOUT_MS = 60000
+const firstLine = s => (s || '').trim().split('\n')[0]
+
+const npmUser = m => String(typeof m === 'object' && m ? m.name : m).split(' <')[0].trim().toLowerCase()
+
+async function npmStatus(ch, { exec }) {
+  if (!ch || !ch.package) return { state: 'not-configured' }
+  const res = await exec('npm', ['view', ch.package, 'version', 'maintainers', '--json'])
+  if (res.error === 'ENOENT') return { state: 'unknown', detail: 'npm is not installed', fix: 'Install Node.js 20 or newer, which includes npm.' }
+  if (res.code === 0 && res.stdout.trim()) {
+    let v
+    try { v = JSON.parse(res.stdout) } catch { return { state: 'unknown', detail: 'npm view printed something that is not JSON' } }
+    const version = Array.isArray(v.version) ? v.version[v.version.length - 1] : v.version
+    const maintainers = [].concat(v.maintainers || []).map(npmUser)
+    let me = ch.maintainer
+    if (!me) {
+      const who = await exec('npm', ['whoami'])
+      if (who.code !== 0 || !who.stdout.trim()) {
+        return { state: 'unknown', version, detail: `${ch.package} ${version} is on npm, but mcpship cannot tell whether it is yours`, fix: 'Run npm login, or add your npm user name as channels.npm.maintainer in publish.json.' }
+      }
+      me = who.stdout.trim()
+    }
+    if (!maintainers.includes(npmUser(me))) {
+      return { state: 'unknown', version, detail: `${ch.package} on npm belongs to ${maintainers.join(', ') || 'someone else'}, not ${me}`, fix: 'Pick another package name in publish.json (channels.npm.package) and in your package.json.' }
+    }
+    return { state: 'published', version }
+  }
+  if (/E404|404 Not Found/.test(res.stderr + res.stdout)) return { state: 'not-published' }
+  return { state: 'unknown', detail: firstLine(res.stderr) || res.error || 'npm view failed' }
+}
+
+async function registryStatus(ch, { fetchFn, dir }) {
+  if (!ch || !ch.name) return { state: 'not-configured' }
+  let localVersion
+  if (ch.server_json) {
+    try { localVersion = JSON.parse(fs.readFileSync(path.resolve(dir, ch.server_json), 'utf8')).version } catch { /* reported as no local version */ }
+  }
+  try {
+    const res = await fetchFn(`${REGISTRY_API}?search=${encodeURIComponent(ch.name)}`, { timeoutMs: REGISTRY_TIMEOUT_MS })
+    if (res.status !== 200) return { state: 'unknown', detail: `registry API returned HTTP ${res.status}` }
+    const data = JSON.parse(res.text)
+    if (!data || !Array.isArray(data.servers)) return { state: 'unknown', detail: 'registry API answered in a shape mcpship does not know' }
+    const entries = data.servers.filter(e => e && (e.server || e).name === ch.name)
+    const versions = entries.map(e => (e.server || e).version)
+    if (!versions.length) return { state: 'not-published', localVersion }
+    const flagged = entries.find(e => ((e._meta || {})['io.modelcontextprotocol.registry/official'] || {}).isLatest)
+    const latest = flagged ? (flagged.server || flagged).version : versions[versions.length - 1]
+    if (localVersion && !versions.includes(localVersion)) return { state: 'outdated', version: latest, localVersion }
+    return { state: 'published', version: localVersion || latest }
+  } catch (e) {
+    return { state: 'unknown', detail: `registry API: ${e.message}` }
+  }
+}
+
+async function pluginStatus(ch, { exec }) {
+  if (!ch || !ch.repo) return { state: 'not-configured' }
+  const repo = await exec('gh', ['api', `repos/${ch.repo}`, '--jq', '.visibility'])
+  if (repo.error === 'ENOENT') return { state: 'unknown', detail: 'gh is not installed', fix: 'Install the GitHub CLI from https://cli.github.com and run gh auth login.' }
+  if (repo.code === 4 || /gh auth login/.test(repo.stderr)) return { state: 'unknown', detail: 'gh is not logged in', fix: 'Run gh auth login.' }
+  if (repo.code !== 0) {
+    if (/Not Found|HTTP 404/.test(repo.stderr)) return { state: 'not-published', detail: `${ch.repo} does not exist` }
+    return { state: 'unknown', detail: firstLine(repo.stderr) || repo.error || 'gh api failed' }
+  }
+  const visibility = repo.stdout.trim()
+  if (visibility !== 'public') return { state: 'not-published', detail: `${ch.repo} is ${visibility}` }
+  const mk = await exec('gh', ['api', `repos/${ch.repo}/contents/.claude-plugin/marketplace.json`, '--jq', '.path'])
+  if (mk.code !== 0) {
+    if (/Not Found|HTTP 404/.test(mk.stderr)) return { state: 'not-published', detail: '.claude-plugin/marketplace.json is missing' }
+    return { state: 'unknown', detail: firstLine(mk.stderr) || mk.error || 'gh api failed' }
+  }
+  return { state: 'published' }
+}
+
+function directoryStatus(ch) {
+  return ch && ch.submitted ? { state: 'published', date: ch.submitted } : { state: 'not-published' }
+}
+
+async function status(cfg, { exec = run, fetchFn = request, dir = process.cwd() } = {}) {
+  const ch = cfg.channels || {}
+  const [npm, registry, plugin] = await Promise.all([
+    npmStatus(ch.npm, { exec }),
+    registryStatus(ch.registry, { fetchFn, dir }),
+    pluginStatus(ch.plugin, { exec }),
+  ])
+  return { npm, registry, plugin, directory: directoryStatus(ch.directory) }
+}
+
+module.exports = { status, npmStatus, REGISTRY_API }

package/lib/checks/auth.js

@@ -0,0 +1,97 @@
+'use strict'
+const { request, rpc, PROTOCOL } = require('../http')
+const { result } = require('../result')
+const { version } = require('../../package.json')
+
+async function getJson(url, timeoutMs) {
+  try {
+    const res = await request(url, { headers: { accept: 'application/json' }, timeoutMs })
+    if (res.status !== 200) return { error: `HTTP ${res.status}` }
+    return { json: JSON.parse(res.text) }
+  } catch (e) {
+    return { error: e instanceof SyntaxError ? 'not JSON' : e.message }
+  }
+}
+
+// RFC 8414: for an issuer with a path, the well-known segment goes between
+// the host and the path. Some servers only serve the appended form.
+function metadataUrls(issuer) {
+  const u = new URL(issuer)
+  const p = u.pathname.replace(/\/$/, '')
+  const trimmed = issuer.replace(/\/$/, '')
+  const urls = []
+  for (const name of ['oauth-authorization-server', 'openid-configuration']) {
+    urls.push(`${u.origin}/.well-known/${name}${p}`)
+    if (p) urls.push(`${trimmed}/.well-known/${name}`)
+  }
+  return urls
+}
+
+async function checkAuth(serverUrl, { timeoutMs } = {}) {
+  const results = []
+  results.push(serverUrl.startsWith('https://')
+    ? result('auth.https', 'pass', 'server URL uses https')
+    : result('auth.https', 'fail', `server URL is not https: ${serverUrl}`, 'Serve the MCP endpoint over https. Claude only connects to https:// URLs.'))
+
+  let first
+  try {
+    first = await rpc(serverUrl, 'initialize', {
+      protocolVersion: PROTOCOL, capabilities: {}, clientInfo: { name: 'mcpship', version },
+    }, { timeoutMs })
+  } catch (e) {
+    results.push(result('auth.www-authenticate', 'fail', `server did not answer: ${e.message}`, 'Check the URL and that the server is running.'))
+    return { mode: 'unknown', registration: [], results }
+  }
+  if (first.status === 200) {
+    results.push(result('auth.www-authenticate', 'skip', 'server answered without sign-in: no-auth server'))
+    return { mode: 'none', registration: [], results }
+  }
+  const www = first.headers.get('www-authenticate') || ''
+  const m = www.match(/resource_metadata="?([^",\s]+)"?/)
+  if (first.status !== 401 || !m) {
+    results.push(result('auth.www-authenticate', 'fail',
+      `unauthenticated initialize returned HTTP ${first.status}${www ? ` with WWW-Authenticate: ${www}` : ' without a WWW-Authenticate header'}`,
+      'Return 401 with WWW-Authenticate: Bearer resource_metadata="<your /.well-known/oauth-protected-resource URL>" so clients can find the sign-in.'))
+    return { mode: 'unknown', registration: [], results }
+  }
+  results.push(result('auth.www-authenticate', 'pass', '401 with resource_metadata'))
+
+  const prm = await getJson(m[1], timeoutMs)
+  const as = prm.json && Array.isArray(prm.json.authorization_servers) && prm.json.authorization_servers[0]
+  if (!as) {
+    results.push(result('auth.resource-metadata', 'fail', `${m[1]}: ${prm.error || 'authorization_servers is missing or empty'}`,
+      'Serve protected resource metadata (RFC 9728) with a non-empty authorization_servers list.'))
+    return { mode: 'oauth', registration: [], results }
+  }
+  results.push(result('auth.resource-metadata', 'pass', `authorization server ${as}`))
+
+  let meta = null
+  let lastError = ''
+  for (const url of metadataUrls(as)) {
+    const got = await getJson(url, timeoutMs)
+    if (got.json && got.json.authorization_endpoint && got.json.token_endpoint) { meta = got.json; break }
+    lastError = got.error || 'authorization_endpoint or token_endpoint missing'
+  }
+  if (!meta) {
+    results.push(result('auth.as-metadata', 'fail', `${as}: ${lastError}`,
+      'Serve authorization server metadata (RFC 8414) at /.well-known/oauth-authorization-server.'))
+    return { mode: 'oauth', registration: [], results }
+  }
+  results.push(result('auth.as-metadata', 'pass', 'authorization server metadata found'))
+
+  const pk = meta.code_challenge_methods_supported || []
+  results.push(pk.includes('S256')
+    ? result('auth.pkce', 'pass', 'PKCE S256 supported')
+    : result('auth.pkce', 'fail', `code_challenge_methods_supported is ${JSON.stringify(pk)}`, 'Support PKCE with S256 and list it in code_challenge_methods_supported.'))
+
+  const registration = []
+  if (meta.client_id_metadata_document_supported === true) registration.push('Client ID Metadata Document')
+  if (meta.registration_endpoint) registration.push('Dynamic Client Registration')
+  results.push(registration.length
+    ? result('auth.client-registration', 'pass', registration.join(' and '))
+    : result('auth.client-registration', 'fail', 'no registration_endpoint, and client_id_metadata_document_supported is not true',
+      'Support Client ID Metadata Documents or Dynamic Client Registration so Claude can register itself.'))
+  return { mode: 'oauth', registration, results }
+}
+
+module.exports = { checkAuth }

package/lib/checks/listing.js

@@ -0,0 +1,93 @@
+'use strict'
+const { request } = require('../http')
+const { result } = require('../result')
+
+const LIMITS = { name: 100, one_liner: 200, description: 2000 }
+const EM_DASH = '\u2014'
+const esc = s => s.replace(/[.*+?^${}()|[\]\\]/g, '\\$&')
+const len = s => [...s].length
+
+async function iconRule(url, { timeoutMs, allowHttp }) {
+  const fix = 'The directory form takes the icon as a public URL. Serve a 512x512 PNG from your own site; a private repo link or an HTML page will not load.'
+  if (!url) return result('listing.icon-url', 'fail', 'listing.icon_url is empty', fix)
+  if (!url.startsWith('https://') && !allowHttp) return result('listing.icon-url', 'fail', `icon URL is not https: ${url}`, fix)
+  try {
+    const res = await request(url, { timeoutMs, maxBytes: 5_000_000 })
+    const type = res.headers.get('content-type') || ''
+    if (res.status === 200 && type.startsWith('image/png')) return result('listing.icon-url', 'pass', `icon is a PNG (${res.bytes} bytes)`)
+    return result('listing.icon-url', 'fail', `${url}: HTTP ${res.status}, content-type ${type || 'none'}`, fix)
+  } catch (e) {
+    return result('listing.icon-url', 'fail', `${url}: ${e.message}`, fix)
+  }
+}
+
+async function pagesRule(L, { timeoutMs }) {
+  const problems = []
+  for (const key of ['docs_url', 'privacy_url', 'terms_url']) {
+    if (!L[key]) { problems.push(`${key} is empty`); continue }
+    try {
+      const res = await request(L[key], { timeoutMs })
+      if (res.status !== 200) problems.push(`${key}: HTTP ${res.status}`)
+    } catch (e) {
+      problems.push(`${key}: ${e.message}`)
+    }
+  }
+  return problems.length
+    ? result('listing.pages', 'fail', problems.join('; '), 'The documentation, privacy and terms pages must be live before you submit.')
+    : result('listing.pages', 'pass', 'documentation, privacy and terms pages load')
+}
+
+function lengthsRule(cfg, L) {
+  const issues = []
+  for (const [field, value, max] of [['name', cfg.name, LIMITS.name], ['one_liner', L.one_liner, LIMITS.one_liner], ['description', L.description, LIMITS.description]]) {
+    if (!value) issues.push(`${field} is empty`)
+    else if (len(value) > max) issues.push(`${field} is ${len(value)} characters (limit ${max})`)
+  }
+  const cats = Array.isArray(L.categories) ? L.categories.filter(Boolean) : []
+  if (cats.length < 1 || cats.length > 5) issues.push(`categories has ${cats.length} entries (1 to 5)`)
+  const ucs = (cfg.use_cases || []).filter(u => u && u.use_case)
+  if (ucs.length < 1 || ucs.length > 3) issues.push(`use_cases has ${ucs.length} filled entries (1 to 3)`)
+  return issues.length
+    ? result('listing.lengths', 'fail', issues.join('; '), 'Fix these fields in publish.json.')
+    : result('listing.lengths', 'pass', 'name, one-liner, description, categories and use cases fit the form')
+}
+
+async function mentionRule(cfg, npmState, { timeoutMs }) {
+  const pkg = cfg.channels && cfg.channels.npm && cfg.channels.npm.package
+  if (!pkg) return result('listing.unpublished-mention', 'skip', 'no npm package configured')
+  if (npmState === 'published') return result('listing.unpublished-mention', 'pass', `${pkg} is on npm`)
+  if (npmState !== 'not-published') return result('listing.unpublished-mention', 'skip', 'npm status unknown')
+  const re = new RegExp(`npx (-y )?${esc(pkg)}(?![\\w.-])`)
+  const hits = []
+  for (const url of cfg.pages_to_scan || []) {
+    try {
+      const res = await request(url, { timeoutMs })
+      if (re.test(res.text)) hits.push(url)
+    } catch { /* an unreachable page cannot advertise anything */ }
+  }
+  return hits.length
+    ? result('listing.unpublished-mention', 'fail', `${hits.join(', ')} tell users to run npx ${pkg}, but ${pkg} is not on npm yet`,
+      'Remove the line until the package is published. Anyone could register the name and collect what users paste into it.')
+    : result('listing.unpublished-mention', 'pass', `no page mentions npx ${pkg}`)
+}
+
+function emDashRule(cfg, L) {
+  const text = [cfg.name, L.one_liner, L.description, cfg.prerequisites, cfg.reviewer && cfg.reviewer.instructions,
+    ...(cfg.use_cases || []).flatMap(u => [u && u.use_case, u && u.prompt])].filter(Boolean).join('\n')
+  return text.includes(EM_DASH)
+    ? result('listing.em-dash', 'warn', 'listing text contains an em-dash', 'Replace it with a comma, colon or full stop before pasting.')
+    : result('listing.em-dash', 'pass', 'no em-dash in listing text')
+}
+
+async function checkListing(cfg, { npmState, timeoutMs, allowHttp = false } = {}) {
+  const L = cfg.listing || {}
+  return [
+    await iconRule(L.icon_url, { timeoutMs, allowHttp }),
+    await pagesRule(L, { timeoutMs }),
+    lengthsRule(cfg, L),
+    await mentionRule(cfg, npmState, { timeoutMs }),
+    emDashRule(cfg, L),
+  ]
+}
+
+module.exports = { checkListing, LIMITS }

package/lib/checks/tools.js

@@ -0,0 +1,63 @@
+'use strict'
+const { rpc, notify, PROTOCOL } = require('../http')
+const { result } = require('../result')
+const { lintTools } = require('../lint')
+const { version } = require('../../package.json')
+
+const MAX_PAGES = 10
+
+function evaluateTools(tools) {
+  const noTitle = tools.filter(t => !t.title && !(t.annotations && t.annotations.title)).map(t => t.name)
+  const noHint = tools.filter(t => {
+    const a = t.annotations || {}
+    return typeof a.readOnlyHint !== 'boolean' && typeof a.destructiveHint !== 'boolean'
+  }).map(t => t.name)
+  return [
+    noTitle.length
+      ? result('tools.title', 'fail', `missing title: ${noTitle.join(', ')}`, 'Add a human-readable title to every tool (tool.title or annotations.title).')
+      : result('tools.title', 'pass', `all ${tools.length} tools have a title`),
+    noHint.length
+      ? result('tools.annotations', 'fail', `missing readOnlyHint or destructiveHint: ${noHint.join(', ')}`, 'Set annotations.readOnlyHint: true on tools that only read, and annotations.destructiveHint on tools that change data.')
+      : result('tools.annotations', 'pass', 'every tool declares readOnlyHint or destructiveHint'),
+    ...lintTools(tools),
+  ]
+}
+
+async function checkTools(serverUrl, { token, authMode, timeoutMs } = {}) {
+  if (authMode === 'oauth' && !token) {
+    return { tools: null, results: [result('tools.reachable', 'skip', 'set MCPSHIP_TOKEN to an access token or API key to check tools')] }
+  }
+  const fail = (message) => ({
+    tools: null,
+    results: [result('tools.reachable', 'fail', message,
+      authMode === 'oauth' ? 'Check that MCPSHIP_TOKEN is a valid access token or API key for this server.' : 'Check that the server answers initialize and tools/list.')],
+  })
+  try {
+    const init = await rpc(serverUrl, 'initialize', {
+      protocolVersion: PROTOCOL, capabilities: {}, clientInfo: { name: 'mcpship', version },
+    }, { token, timeoutMs, id: 1 })
+    if (init.status !== 200 || !init.message || init.message.error) {
+      const why = init.message && init.message.error ? `: ${init.message.error.message}` : ''
+      return fail(`initialize returned HTTP ${init.status}${why}`)
+    }
+    const sessionId = init.headers.get('mcp-session-id') || undefined
+    await notify(serverUrl, 'notifications/initialized', { token, sessionId, timeoutMs }).catch(() => {})
+    const tools = []
+    let cursor
+    for (let page = 0; page < MAX_PAGES; page++) {
+      const res = await rpc(serverUrl, 'tools/list', cursor ? { cursor } : {}, { token, sessionId, timeoutMs, id: page + 2 })
+      if (res.status !== 200 || !res.message || !res.message.result) {
+        const why = res.message && res.message.error ? `: ${res.message.error.message}` : ''
+        return fail(`tools/list returned HTTP ${res.status}${why}`)
+      }
+      tools.push(...(res.message.result.tools || []))
+      cursor = res.message.result.nextCursor
+      if (!cursor) break
+    }
+    return { tools, results: [result('tools.reachable', 'pass', `${tools.length} tools listed`), ...evaluateTools(tools)] }
+  } catch (e) {
+    return fail(`server did not answer: ${e.message}`)
+  }
+}
+
+module.exports = { checkTools, evaluateTools }

package/lib/commands.js

@@ -0,0 +1,77 @@
+'use strict'
+const fs = require('fs')
+const path = require('path')
+const config = require('./config')
+const channels = require('./channels')
+const { checkAuth } = require('./checks/auth')
+const { checkTools } = require('./checks/tools')
+const { checkListing } = require('./checks/listing')
+const { renderPacket, writePacket, PACKET_PATH } = require('./packet')
+const { nextStep } = require('./next')
+const { summarize } = require('./result')
+const { run } = require('./exec')
+
+class UsageError extends Error {}
+
+function loadOrThrow(dir) {
+  const loaded = config.load(dir)
+  if (!loaded.config) throw new UsageError(loaded.errors.join('\n'))
+  return loaded.config
+}
+
+async function check({ dir, url, token, deps = {} }) {
+  const loaded = config.load(dir)
+  if (loaded.exists && !loaded.config) throw new UsageError(loaded.errors.join('\n'))
+  const cfg = loaded.config
+  const serverUrl = url || (cfg && cfg.server_url)
+  if (!serverUrl) throw new UsageError('give a server URL (mcpship check <url>) or create publish.json with mcpship init <url>')
+  const auth = await checkAuth(serverUrl)
+  const tools = await checkTools(serverUrl, { token, authMode: auth.mode })
+  let listing = []
+  if (cfg) {
+    const npm = await channels.npmStatus(cfg.channels && cfg.channels.npm, { exec: deps.exec || run })
+    listing = await checkListing(cfg, { npmState: npm.state })
+  }
+  const results = [...auth.results, ...tools.results, ...listing]
+  return { serverUrl, auth: { mode: auth.mode, registration: auth.registration }, tools: tools.tools, results, summary: summarize(results) }
+}
+
+async function packet({ dir, token, deps }) {
+  const cfg = loadOrThrow(dir)
+  const c = await check({ dir, token, deps })
+  const { text, missing } = renderPacket(cfg, { auth: c.auth, tools: c.tools })
+  return { path: writePacket(dir, text), missing }
+}
+
+async function status({ dir, deps = {} }) {
+  const cfg = loadOrThrow(dir)
+  return channels.status(cfg, { ...deps, dir })
+}
+
+async function next({ dir, token, deps = {} }) {
+  const cfg = loadOrThrow(dir)
+  const [c, st] = await Promise.all([check({ dir, token, deps }), channels.status(cfg, { ...deps, dir })])
+  return nextStep({ cfg, check: c.summary, channels: st, packetExists: fs.existsSync(path.join(dir, PACKET_PATH)) })
+}
+
+function done({ dir, channel }) {
+  if (channel !== 'directory') {
+    throw new UsageError(`only the directory is confirmed by hand; ${channel || 'that channel'} is detected automatically (see mcpship status)`)
+  }
+  const cfg = loadOrThrow(dir)
+  const date = new Date().toISOString().slice(0, 10)
+  cfg.channels = cfg.channels || {}
+  cfg.channels.directory = { ...(cfg.channels.directory || {}), submitted: date }
+  config.save(dir, cfg)
+  return { channel, date }
+}
+
+function init({ dir, url }) {
+  if (!url) throw new UsageError('give the server URL: mcpship init https://example.com/mcp')
+  const file = path.join(dir, config.FILE)
+  if (fs.existsSync(file)) throw new UsageError(`${config.FILE} already exists in ${dir}`)
+  config.save(dir, config.template(url))
+  return { path: file }
+}
+
+module.exports = { UsageError, check, packet, next, status, done, init }

package/lib/config.js

@@ -0,0 +1,74 @@
+'use strict'
+const fs = require('fs')
+const path = require('path')
+
+const FILE = 'publish.json'
+const ACCESS = ['read', 'write', 'both']
+const OWNERSHIP = ['own', 'partner', 'third_party']
+
+function validate(cfg) {
+  if (!cfg || typeof cfg !== 'object' || Array.isArray(cfg)) return [`${FILE} must be a JSON object`]
+  const errors = []
+  if (typeof cfg.server_url !== 'string' || !cfg.server_url) errors.push('server_url is required')
+  if (cfg.access !== undefined && cfg.access !== '' && !ACCESS.includes(cfg.access)) {
+    errors.push(`access must be one of ${ACCESS.join(', ')}`)
+  }
+  const own = cfg.data_handling && cfg.data_handling.api_ownership
+  if (own !== undefined && own !== '' && !OWNERSHIP.includes(own)) {
+    errors.push(`data_handling.api_ownership must be one of ${OWNERSHIP.join(', ')}`)
+  }
+  for (const k of ['health_data', 'sponsored']) {
+    const v = cfg.data_handling && cfg.data_handling[k]
+    if (v !== undefined && v !== null && typeof v !== 'boolean') errors.push(`data_handling.${k} must be true or false`)
+  }
+  const npm = cfg.channels && cfg.channels.npm
+  if (npm && npm.maintainer !== undefined && typeof npm.maintainer !== 'string') errors.push('channels.npm.maintainer must be a string')
+  if (cfg.use_cases !== undefined && !Array.isArray(cfg.use_cases)) errors.push('use_cases must be a list')
+  if (cfg.channels !== undefined && (typeof cfg.channels !== 'object' || Array.isArray(cfg.channels))) {
+    errors.push('channels must be an object')
+  }
+  return errors
+}
+
+function load(dir) {
+  const file = path.join(dir, FILE)
+  let raw
+  try {
+    raw = fs.readFileSync(file, 'utf8')
+  } catch {
+    return { exists: false, config: null, errors: [`${FILE} not found in ${dir} (create one with: mcpship init <server-url>)`] }
+  }
+  let cfg
+  try {
+    cfg = JSON.parse(raw)
+  } catch (e) {
+    return { exists: true, config: null, errors: [`${FILE} is not valid JSON: ${e.message}`] }
+  }
+  const errors = validate(cfg)
+  return { exists: true, config: errors.length ? null : cfg, errors }
+}
+
+function save(dir, cfg) {
+  fs.writeFileSync(path.join(dir, FILE), JSON.stringify(cfg, null, 2) + '\n')
+}
+
+function template(serverUrl) {
+  return {
+    name: '',
+    server_url: serverUrl,
+    listing: {
+      one_liner: '', description: '', categories: [],
+      docs_url: '', privacy_url: '', terms_url: '', support_email: '', icon_url: '',
+    },
+    use_cases: [{ use_case: '', prompt: '' }],
+    prerequisites: '',
+    access: '',
+    company: { name: '', website: '', contact_name: '', contact_email: '', role: '' },
+    data_handling: { api_ownership: '', health_data: null, sponsored: null, notes: '' },
+    reviewer: { instructions: '' },
+    pages_to_scan: [],
+    channels: {},
+  }
+}
+
+module.exports = { FILE, validate, load, save, template }

package/lib/exec.js

@@ -0,0 +1,14 @@
+'use strict'
+const { execFile } = require('child_process')
+
+function run(cmd, args, { timeoutMs = 30000, cwd } = {}) {
+  return new Promise(resolve => {
+    execFile(cmd, args, { timeout: timeoutMs, cwd, maxBuffer: 4_000_000 }, (err, stdout, stderr) => {
+      if (err && err.code === 'ENOENT') return resolve({ code: null, stdout: '', stderr: '', error: 'ENOENT' })
+      if (err && err.killed) return resolve({ code: null, stdout: stdout || '', stderr: stderr || '', error: 'timeout' })
+      resolve({ code: err ? (typeof err.code === 'number' ? err.code : 1) : 0, stdout: stdout || '', stderr: stderr || '' })
+    })
+  })
+}
+
+module.exports = { run }

package/lib/format.js

@@ -0,0 +1,34 @@
+'use strict'
+
+function redact(text, token) {
+  if (!token) return String(text)
+  const escaped = JSON.stringify(token).slice(1, -1)
+  return String(text).split(escaped).join('***').split(token).join('***')
+}
+
+const LABEL = { pass: 'PASS', fail: 'FAIL', warn: 'WARN', skip: 'SKIP' }
+
+function formatCheck(data) {
+  const lines = [`Server: ${data.serverUrl}`, `Sign-in: ${data.auth.mode}`, '']
+  for (const r of data.results) {
+    lines.push(`${LABEL[r.status].padEnd(5)} ${r.id.padEnd(28)} ${r.message}`)
+    if (r.fix && (r.status === 'fail' || r.status === 'warn')) lines.push(`      fix: ${r.fix}`)
+  }
+  const s = data.summary
+  lines.push('', `${s.pass} passed, ${s.fail} failed, ${s.warn} warnings, ${s.skip} skipped`)
+  return lines.join('\n')
+}
+
+function formatStatus(st) {
+  const row = (name, c) => {
+    const extra = [c.version && `version ${c.version}`, c.localVersion && `local ${c.localVersion}`, c.date && `on ${c.date}`, c.detail].filter(Boolean).join(', ')
+    return `${name.padEnd(10)} ${c.state}${extra ? ` (${extra})` : ''}${c.fix ? `\n           fix: ${c.fix}` : ''}`
+  }
+  return [row('npm', st.npm), row('registry', st.registry), row('plugin', st.plugin), row('directory', st.directory)].join('\n')
+}
+
+function formatNext(n) {
+  return [`Next: ${n.title}`, '', ...n.instructions.map(l => (l.startsWith('  ') ? l : `- ${l}`))].join('\n')
+}
+
+module.exports = { redact, formatCheck, formatStatus, formatNext }

package/lib/http.js

@@ -0,0 +1,67 @@
+'use strict'
+const { version } = require('../package.json')
+
+const PROTOCOL = '2025-06-18'
+
+async function request(url, { method = 'GET', headers = {}, body, timeoutMs = 10000, maxBytes = 1_000_000 } = {}) {
+  const ctrl = new AbortController()
+  const timer = setTimeout(() => ctrl.abort(), timeoutMs)
+  try {
+    const res = await fetch(url, {
+      method, body, redirect: 'follow', signal: ctrl.signal,
+      headers: { 'user-agent': `mcpship/${version}`, ...headers },
+    })
+    const buf = Buffer.from(await res.arrayBuffer())
+    if (buf.length > maxBytes) throw new Error(`response larger than ${maxBytes} bytes`)
+    return { status: res.status, headers: res.headers, text: buf.toString('utf8'), bytes: buf.length }
+  } catch (e) {
+    if (e.name === 'AbortError') throw new Error('timeout')
+    if (e.cause && e.cause.code) throw new Error(e.cause.code)
+    throw e
+  } finally {
+    clearTimeout(timer)
+  }
+}
+
+function parseRpc(text, contentType = '') {
+  if (contentType.includes('text/event-stream')) {
+    let last = null
+    for (const line of text.split(/\r?\n/)) {
+      if (!line.startsWith('data:')) continue
+      try {
+        const m = JSON.parse(line.slice(5).trim())
+        if (m && (m.result !== undefined || m.error !== undefined)) last = m
+      } catch { /* a non-JSON data line is not the response */ }
+    }
+    return last
+  }
+  try { return JSON.parse(text) } catch { return null }
+}
+
+function rpcHeaders(token, sessionId) {
+  const h = {
+    'content-type': 'application/json',
+    accept: 'application/json, text/event-stream',
+    'mcp-protocol-version': PROTOCOL,
+  }
+  if (token) h.authorization = `Bearer ${token}`
+  if (sessionId) h['mcp-session-id'] = sessionId
+  return h
+}
+
+async function rpc(url, method, params, { token, id = 1, sessionId, timeoutMs } = {}) {
+  const res = await request(url, {
+    method: 'POST', timeoutMs, headers: rpcHeaders(token, sessionId),
+    body: JSON.stringify({ jsonrpc: '2.0', id, method, params }),
+  })
+  return { status: res.status, headers: res.headers, message: parseRpc(res.text, res.headers.get('content-type') || '') }
+}
+
+async function notify(url, method, { token, sessionId, timeoutMs } = {}) {
+  await request(url, {
+    method: 'POST', timeoutMs, headers: rpcHeaders(token, sessionId),
+    body: JSON.stringify({ jsonrpc: '2.0', method }),
+  })
+}
+
+module.exports = { PROTOCOL, request, parseRpc, rpc, notify }

package/lib/lint.js

@@ -0,0 +1,51 @@
+'use strict'
+const { result } = require('./result')
+
+// The directory compliance step: tool descriptions hold no instructions about
+// model behaviour or other tools, and no hidden or encoded text.
+const INSTRUCTION_PATTERNS = [
+  /\buse (it|this|this tool) (first|before|after|instead)\b/i,
+  /\b(always|never) (call|use|invoke)\b/i,
+  /\byou (must|should)\b/i,
+  /\bignore (all|previous|the above)\b/i,
+  /\bsystem prompt\b/i,
+]
+const HIDDEN = /[\u200B-\u200F\u202A-\u202E\u2060\uFEFF]/
+const BASE64 = /[A-Za-z0-9+/]{40,}={0,2}/
+const esc = s => s.replace(/[.*+?^${}()|[\]\\]/g, '\\$&')
+
+function lintTools(tools) {
+  const instructions = []
+  const hidden = []
+  const mentions = []
+  const names = tools.map(t => t.name)
+  for (const t of tools) {
+    const d = t.description || ''
+    for (const p of INSTRUCTION_PATTERNS) {
+      const m = d.match(p)
+      if (m) instructions.push(`${t.name}: "${m[0]}"`)
+    }
+    for (const other of names) {
+      if (other === t.name) continue
+      const call = d.match(new RegExp(`\\b(call|use|invoke|run) (the )?\`?${esc(other)}\\b`, 'i'))
+      if (call) instructions.push(`${t.name}: "${call[0]}"`)
+      else if (new RegExp(`\\b${esc(other)}\\b`).test(d)) mentions.push(`${t.name} names ${other}`)
+    }
+    if (HIDDEN.test(d)) hidden.push(`${t.name}: invisible character`)
+    const b = d.match(BASE64)
+    if (b) hidden.push(`${t.name}: encoded-looking text "${b[0].slice(0, 20)}..."`)
+  }
+  return [
+    instructions.length
+      ? result('tools.instructions', 'fail', instructions.join('; '), 'Describe what the tool does and returns, as a fact. Remove sentences that tell the model what to do or which tool to call.')
+      : result('tools.instructions', 'pass', 'no instructions in tool descriptions'),
+    hidden.length
+      ? result('tools.hidden-text', 'fail', hidden.join('; '), 'Remove invisible characters and encoded text from descriptions.')
+      : result('tools.hidden-text', 'pass', 'no hidden or encoded text'),
+    mentions.length
+      ? result('tools.mentions', 'warn', mentions.join('; '), 'Usually accepted. If a reviewer objects, describe the behaviour without naming the other tool.')
+      : result('tools.mentions', 'pass', 'no description names another tool'),
+  ]
+}
+
+module.exports = { lintTools, INSTRUCTION_PATTERNS }

package/lib/mcp.js

@@ -0,0 +1,115 @@
+'use strict'
+const readline = require('readline')
+const commands = require('./commands')
+const { redact, formatCheck, formatStatus, formatNext } = require('./format')
+const { version } = require('../package.json')
+
+const VERSIONS = ['2025-11-25', '2025-06-18', '2025-03-26']
+const DIR = { type: 'string', description: 'Folder that holds publish.json. Defaults to the folder the server was started in.' }
+const READ = { readOnlyHint: true, destructiveHint: false, idempotentHint: true, openWorldHint: true }
+const LOCAL_WRITE = { readOnlyHint: false, destructiveHint: false, idempotentHint: true, openWorldHint: false }
+
+const TOOLS = [
+  {
+    name: 'mcpship_check',
+    title: 'Check an MCP server against the Claude directory rules',
+    description: 'Tests a remote MCP server: OAuth discovery, PKCE and client registration, tool titles and annotations, instruction-free descriptions, and the listing (icon URL, pages, field lengths). Lists tools when MCPSHIP_TOKEN is set in the environment. Returns each rule as pass, fail, warn or skip, with a fix for every failure.',
+    inputSchema: { type: 'object', properties: { url: { type: 'string', description: 'Server URL. Defaults to server_url in publish.json.' }, dir: DIR } },
+    annotations: { title: 'Check server', ...READ },
+  },
+  {
+    name: 'mcpship_next',
+    title: 'Next publishing step',
+    description: 'Returns the first unfinished publishing step (check, npm, MCP Registry, plugin repo, submission text, directory) with the exact command or click for it. Reads the live state of every channel.',
+    inputSchema: { type: 'object', properties: { dir: DIR } },
+    annotations: { title: 'Next step', ...READ },
+  },
+  {
+    name: 'mcpship_status',
+    title: 'Publishing status',
+    description: 'Returns the live state of npm, the MCP Registry, the Claude Code plugin repo and the Claude directory submission for the project in publish.json.',
+    inputSchema: { type: 'object', properties: { dir: DIR } },
+    annotations: { title: 'Status', ...READ },
+  },
+  {
+    name: 'mcpship_packet',
+    title: 'Write the directory submission text',
+    description: 'Writes docs/directory/submission.md next to publish.json: the text for each step of the Claude directory form, in portal order. Fields missing from publish.json are marked MISSING.',
+    inputSchema: { type: 'object', properties: { dir: DIR } },
+    annotations: { title: 'Write packet', ...LOCAL_WRITE },
+  },
+  {
+    name: 'mcpship_done',
+    title: 'Record the directory submission',
+    description: 'Records in publish.json that the Claude directory form was submitted today. The directory has no public status API, so this is the only manually confirmed step.',
+    inputSchema: { type: 'object', properties: { channel: { type: 'string', enum: ['directory'] }, dir: DIR }, required: ['channel'] },
+    annotations: { title: 'Mark submitted', ...LOCAL_WRITE },
+  },
+]
+
+async function callTool(name, args, token) {
+  const dir = args.dir || process.cwd()
+  switch (name) {
+    case 'mcpship_check': { const r = await commands.check({ dir, url: args.url, token }); return [r, formatCheck(r)] }
+    case 'mcpship_next': { const r = await commands.next({ dir, token }); return [r, formatNext(r)] }
+    case 'mcpship_status': { const r = await commands.status({ dir }); return [r, formatStatus(r)] }
+    case 'mcpship_packet': {
+      const r = await commands.packet({ dir, token })
+      return [r, `Wrote ${r.path}.${r.missing.length ? ` Missing in publish.json: ${r.missing.join(', ')}` : ''}`]
+    }
+    case 'mcpship_done': { const r = commands.done({ dir, channel: args.channel }); return [r, `Recorded: ${r.channel} submitted on ${r.date}.`] }
+    default: return null
+  }
+}
+
+async function handle(msg, { token }) {
+  const reply = result => ({ jsonrpc: '2.0', id: msg.id, result })
+  const error = (code, message) => ({ jsonrpc: '2.0', id: msg.id, error: { code, message } })
+  if (msg.id === undefined) return null
+  switch (msg.method) {
+    case 'initialize': {
+      const asked = msg.params && msg.params.protocolVersion
+      return reply({
+        protocolVersion: VERSIONS.includes(asked) ? asked : VERSIONS[0],
+        capabilities: { tools: {} },
+        serverInfo: { name: 'mcpship', version },
+      })
+    }
+    case 'ping': return reply({})
+    case 'tools/list': return reply({ tools: TOOLS })
+    case 'tools/call': {
+      const p = msg.params || {}
+      if (!TOOLS.some(t => t.name === p.name)) return error(-32602, `Unknown tool: ${p.name}`)
+      try {
+        const [data, text] = await callTool(p.name, p.arguments || {}, token)
+        return reply({ content: [{ type: 'text', text: redact(text, token) }], structuredContent: JSON.parse(redact(JSON.stringify(data), token)) })
+      } catch (e) {
+        return reply({ content: [{ type: 'text', text: redact(e.message, token) }], isError: true })
+      }
+    }
+    default: return error(-32601, `Method not found: ${msg.method}`)
+  }
+}
+
+function serve(input, output, { token } = {}) {
+  const rl = readline.createInterface({ input })
+  rl.on('line', async line => {
+    if (!line.trim()) return
+    let msg
+    try { msg = JSON.parse(line) } catch {
+      output.write(JSON.stringify({ jsonrpc: '2.0', id: null, error: { code: -32700, message: 'Parse error' } }) + '\n')
+      return
+    }
+    if (!msg || typeof msg !== 'object' || Array.isArray(msg)) {
+      output.write(JSON.stringify({ jsonrpc: '2.0', id: null, error: { code: -32600, message: 'Invalid request: send one JSON-RPC object per line' } }) + '\n')
+      return
+    }
+    let out
+    try { out = await handle(msg, { token }) } catch (e) {
+      out = { jsonrpc: '2.0', id: msg.id === undefined ? null : msg.id, error: { code: -32603, message: redact(e.message, token) } }
+    }
+    if (out) output.write(JSON.stringify(out) + '\n')
+  })
+}
+
+module.exports = { serve, handle, TOOLS }

package/lib/next.js

@@ -0,0 +1,90 @@
+'use strict'
+
+const unknownLines = st => (st.state === 'unknown' ? [`Status unknown: ${st.detail || 'no detail'}.`, ...(st.fix ? [st.fix] : [])] : [])
+
+function npmStep(ch, st) {
+  return {
+    step: 'npm',
+    title: `Publish ${ch.package} to npm`,
+    instructions: [
+      ...unknownLines(st),
+      `Publish ${ch.package} from its package folder.`,
+      'With two-factor authentication on, the smoothest way is a Granular Access Token: on npmjs.com open Access Tokens, Generate New Token, Granular Access Token, give it read and write access to packages and tick "Bypass two-factor authentication".',
+      'Keep the token in the NPM_TOKEN environment variable, then publish through a temporary config file and delete it:',
+      '  (umask 077; printf "//registry.npmjs.org/:_authToken=%s\\n" "$NPM_TOKEN" > /tmp/mcpship-npmrc) && npm publish --access public --userconfig /tmp/mcpship-npmrc; rm -f /tmp/mcpship-npmrc',
+      'Fallback: npm publish --access public --otp=123456, with the current 6-digit code from the authenticator app you set up for npm. The code changes every 30 seconds, and recovery codes do not work here.',
+      'Then run mcpship status: npm shows as published.',
+    ],
+  }
+}
+
+function registryStep(ch, st) {
+  return {
+    step: 'registry',
+    title: `Publish ${ch.name} to the MCP Registry`,
+    instructions: [
+      ...unknownLines(st),
+      ...(st.state === 'outdated' ? [`The registry has ${st.version} and your server.json says ${st.localVersion}: publish the new version.`] : []),
+      'Install mcp-publisher if you do not have it: download it for your system from https://github.com/modelcontextprotocol/registry/releases.',
+      `In the folder with server.json${ch.server_json ? ` (${ch.server_json})` : ''}, run: mcp-publisher login github, then mcp-publisher publish.`,
+      'With GitHub login the name must start with io.github.<your-github-user>/, and the description must be 100 characters or fewer.',
+      'Then run mcpship status: the registry shows as published.',
+    ],
+  }
+}
+
+function pluginStep(ch, st, cfg) {
+  return {
+    step: 'plugin',
+    title: `Publish the Claude Code plugin repo ${ch.repo}`,
+    instructions: [
+      ...unknownLines(st),
+      ...(st.detail && st.state !== 'unknown' ? [`Now: ${st.detail}.`] : []),
+      'The repo needs .claude-plugin/marketplace.json listing your plugin, and plugins/<name>/.claude-plugin/plugin.json plus plugins/<name>/.mcp.json containing:',
+      `  {"mcpServers": {"<name>": {"type": "http", "url": "${cfg.server_url}"}}}`,
+      `Create it public and push: gh repo create ${ch.repo} --public --source . --push`,
+      `Users then install it with /plugin marketplace add ${ch.repo} and /plugin install <name>@<marketplace-name>.`,
+    ],
+  }
+}
+
+function nextStep({ cfg, check, channels, packetExists }) {
+  if (!check || check.fail > 0) {
+    return {
+      step: 'check',
+      title: 'Make mcpship check pass',
+      instructions: check
+        ? [`${check.fail} rule(s) fail. Run mcpship check and fix each one; every failure prints its fix.`]
+        : ['Run mcpship check. Set MCPSHIP_TOKEN to an access token or API key so the tools are checked too.'],
+    }
+  }
+  const ch = cfg.channels || {}
+  if (ch.npm && channels.npm.state !== 'published') return npmStep(ch.npm, channels.npm)
+  if (ch.registry && channels.registry.state !== 'published') return registryStep(ch.registry, channels.registry)
+  if (ch.plugin && channels.plugin.state !== 'published') return pluginStep(ch.plugin, channels.plugin, cfg)
+  if (!packetExists) {
+    return {
+      step: 'packet',
+      title: 'Write the directory submission text',
+      instructions: ['Run mcpship packet. It writes docs/directory/submission.md with the text for every form step. Fix any MISSING line in publish.json and run it again.'],
+    }
+  }
+  if (channels.directory.state !== 'published') {
+    return {
+      step: 'directory',
+      title: 'Submit to the Claude connector directory',
+      instructions: [
+        'Open https://claude.ai/directory/manage, choose "Submit new", then "MCP connector". Any paid Claude plan can submit.',
+        'Paste each step from docs/directory/submission.md. The icon is a public URL, not a file.',
+        'Afterwards run mcpship done directory.',
+      ],
+    }
+  }
+  return {
+    step: 'done',
+    title: 'Everything is published',
+    instructions: ['npm, the MCP Registry, the plugin and the directory submission are done. Run mcpship status any time to re-check.'],
+  }
+}
+
+module.exports = { nextStep }

package/lib/packet.js

@@ -0,0 +1,119 @@
+'use strict'
+const fs = require('fs')
+const path = require('path')
+const { LIMITS } = require('./checks/listing')
+
+const PACKET_PATH = 'docs/directory/submission.md'
+const ACCESS_LABEL = { read: 'Read only', write: 'Write only', both: 'Read and write' }
+const OWN_LABEL = { own: 'We own the API', partner: "We proxy a partner's API with permission", third_party: "Calls a third-party API we don't control" }
+
+function renderPacket(cfg, { auth = null, tools = null } = {}) {
+  const missing = []
+  const val = (v, field) => {
+    if (v === undefined || v === null || v === '' || (Array.isArray(v) && !v.length)) {
+      missing.push(field)
+      return `MISSING: ${field}`
+    }
+    return Array.isArray(v) ? v.join(', ') : String(v)
+  }
+  const count = (v, max) => (v.startsWith('MISSING: ') ? '' : ` (${[...v].length}/${max} characters)`)
+  const yesNo = (v, field) => (typeof v === 'boolean' ? (v ? 'Yes' : 'No') : val(null, field))
+  const L = cfg.listing || {}
+  const C = cfg.company || {}
+  const D = cfg.data_handling || {}
+  const out = []
+  const push = (...lines) => out.push(...lines)
+
+  push(`# Claude connector directory: submission text for ${cfg.name || 'this server'}`, '',
+    'Generated by mcpship. Open https://claude.ai/directory/manage, choose "Submit new", then "MCP connector", and paste each value into the step with the same name. Any paid Claude plan can submit.', '')
+
+  push('## 1. Connection', '', `- Server URL: ${val(cfg.server_url, 'server_url')}`, '')
+
+  push('## 2. Tools', '')
+  if (tools) {
+    push('The portal syncs these from the server. Every tool needs a title and a readOnlyHint or destructiveHint.', '',
+      '| Tool | Title | Read only | Destructive |', '| --- | --- | --- | --- |')
+    for (const t of tools) {
+      const a = t.annotations || {}
+      const show = v => (v === undefined ? '' : String(v))
+      push(`| ${t.name} | ${t.title || a.title || ''} | ${show(a.readOnlyHint)} | ${show(a.destructiveHint)} |`)
+    }
+    push('')
+  } else {
+    push('Not listed: run `mcpship check` with MCPSHIP_TOKEN set to include the tool table.', '')
+  }
+
+  const name = val(cfg.name, 'name')
+  const one = val(L.one_liner, 'listing.one_liner')
+  const desc = val(L.description, 'listing.description')
+  push('## 3. Listing', '',
+    `- Server name${count(name, LIMITS.name)}: ${name}`,
+    `- One-liner${count(one, LIMITS.one_liner)}: ${one}`,
+    `- Categories: ${val(L.categories, 'listing.categories')}`,
+    `- Documentation URL: ${val(L.docs_url, 'listing.docs_url')}`,
+    `- Privacy policy URL: ${val(L.privacy_url, 'listing.privacy_url')}`,
+    `- Terms URL (if asked): ${val(L.terms_url, 'listing.terms_url')}`,
+    `- Support contact: ${val(L.support_email, 'listing.support_email')}`,
+    `- Icon URL: ${val(L.icon_url, 'listing.icon_url')}`,
+    '', `Description${count(desc, LIMITS.description)}:`, '', desc, '')
+
+  push('## 4. Use cases', '')
+  const ucs = (cfg.use_cases || []).filter(u => u && u.use_case)
+  if (!ucs.length) push(`- ${val(null, 'use_cases')}`)
+  ucs.forEach((u, i) => push(`- Use case ${i + 1}: ${u.use_case}`, `  - Example prompt ${i + 1}: ${val(u.prompt, `use_cases[${i}].prompt`)}`))
+  push('', `- Prerequisites: ${val(cfg.prerequisites, 'prerequisites')}`,
+    `- Read / write capabilities: ${ACCESS_LABEL[cfg.access] || val(null, 'access')}`, '')
+
+  push('## 5. Company', '',
+    `- Company name: ${val(C.name, 'company.name')}`,
+    `- Company website: ${val(C.website, 'company.website')}`,
+    `- Full name: ${val(C.contact_name, 'company.contact_name')}`,
+    `- Email: ${val(C.contact_email, 'company.contact_email')}`,
+    `- Role: ${val(C.role, 'company.role')}`,
+    '- Anthropic contact: leave empty unless you have one', '')
+
+  push('## 6. Authentication', '')
+  if (auth && auth.mode === 'oauth') {
+    const client = auth.registration.includes('Client ID Metadata Document') ? 'Client ID Metadata Document' : 'Dynamic Client Registration'
+    push('- Authentication requirement: Always required', '- Authentication methods: OAuth sign-in',
+      `- OAuth client: ${client} (the server supports: ${auth.registration.join(' and ') || 'none detected'})`,
+      '- Additional request headers: leave empty', '')
+  } else if (auth && auth.mode === 'none') {
+    push('- Authentication requirement: None', '')
+  } else {
+    push('Not detected: run `mcpship check` first.', '')
+  }
+
+  push('## 7. Data handling', '',
+    `- API ownership: ${OWN_LABEL[D.api_ownership] || val(null, 'data_handling.api_ownership')}`,
+    `- Personal health data: ${yesNo(D.health_data, 'data_handling.health_data')}`,
+    `- Sponsored or promoted content: ${yesNo(D.sponsored, 'data_handling.sponsored')}`)
+  if (D.notes) push('', 'Additional notes:', '', D.notes)
+  push('')
+
+  push('## 8. Test & launch', '', 'Test setup instructions:', '', '```',
+    val(cfg.reviewer && cfg.reviewer.instructions, 'reviewer.instructions'), '```', '',
+    '- Self-tested: tick it only after you have called every tool yourself, as a custom connector in Claude or with MCP Inspector.', '')
+
+  push('## 9. Compliance', '',
+    'Tick all seven acknowledgements. They hold when `mcpship check` passes and:', '',
+    '- the server calls your own API, or a partner API you may proxy;',
+    '- it moves no money and generates no images, video or audio;',
+    '- no tool description gives instructions to the model (rule tools.instructions);',
+    '- it collects no conversation data beyond what its tools need;',
+    '- the documentation URL is live (rule listing.pages).', '')
+
+  push('## 10. Review and submit', '',
+    'Read any quality warnings, then submit. Afterwards run `mcpship done directory`. Escalations: mcp-review@anthropic.com.', '')
+
+  return { text: out.join('\n'), missing }
+}
+
+function writePacket(dir, text) {
+  const file = path.join(dir, PACKET_PATH)
+  fs.mkdirSync(path.dirname(file), { recursive: true })
+  fs.writeFileSync(file, text)
+  return file
+}
+
+module.exports = { renderPacket, writePacket, PACKET_PATH }

package/lib/result.js

@@ -0,0 +1,13 @@
+'use strict'
+
+function result(id, status, message, fix) {
+  return fix ? { id, status, message, fix } : { id, status, message }
+}
+
+function summarize(results) {
+  const s = { pass: 0, fail: 0, warn: 0, skip: 0 }
+  for (const r of results) s[r.status] += 1
+  return s
+}
+
+module.exports = { result, summarize }

package/package.json

@@ -1,6 +1,16 @@
 {
   "name": "mcpship",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "version": "0.1.0",
+  "description": "Check a remote MCP server against the Claude directory rules and publish it: npm, MCP Registry, Claude Code plugin, Claude connector directory.",
+  "bin": { "mcpship": "bin/mcpship.js" },
+  "main": "lib/commands.js",
+  "files": ["bin/", "lib/", "README.md", "LICENSE"],
+  "scripts": { "test": "node --test test/*.test.js" },
+  "engines": { "node": ">=20" },
+  "keywords": ["mcp", "model-context-protocol", "claude", "connector", "plugin", "mcp-registry", "publish", "cli"],
+  "repository": { "type": "git", "url": "git+https://github.com/emanueltns/mcpship.git" },
+  "homepage": "https://github.com/emanueltns/mcpship",
+  "license": "MIT",
+  "author": "Freeapp SRL <contact@freeapp.ai>",
+  "mcpName": "io.github.emanueltns/mcpship"
+}