@namingsignal/mcp 0.2.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Zena Labs LLC
+
+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

@@ -0,0 +1,75 @@
+# @namingsignal/mcp
+
+Stdio [Model Context Protocol](https://modelcontextprotocol.io) server for [NamingSignal](https://namingsignal.com): evidence-first product naming with exact domain registry checks, developer namespace checks, and source-backed finalist research. All five tools are read-only and are metered through the NamingSignal account attached to your API key.
+
+Create a free API key at https://namingsignal.com/developers/keys.
+
+## Fastest option: remote MCP, no install
+
+NamingSignal also serves the identical tool surface over Streamable HTTP at `https://namingsignal.com/mcp`. If your client supports remote MCP servers, you do not need this package at all.
+
+Claude Code:
+
+```bash
+claude mcp add --transport http naming-signal https://namingsignal.com/mcp \
+  --header "Authorization: Bearer YOUR_NAMINGSIGNAL_KEY"
+```
+
+Codex `~/.codex/config.toml`:
+
+```toml
+experimental_use_rmcp_client = true
+
+[mcp_servers.naming_signal]
+url = "https://namingsignal.com/mcp"
+bearer_token_env_var = "NAMING_SIGNAL_API_KEY"
+```
+
+## Stdio setup
+
+The stdio server runs locally and calls the hosted REST API (default `https://namingsignal.com`).
+
+Claude Code:
+
+```bash
+claude mcp add naming-signal \
+  --env NAMING_SIGNAL_API_KEY=YOUR_NAMINGSIGNAL_KEY \
+  -- npx -y @namingsignal/mcp
+```
+
+Codex `~/.codex/config.toml`:
+
+```toml
+[mcp_servers.naming_signal]
+command = "npx"
+args = ["-y", "@namingsignal/mcp"]
+env = { NAMING_SIGNAL_API_KEY = "YOUR_NAMINGSIGNAL_KEY" }
+tool_timeout_sec = 360
+```
+
+Large sprints (150 to 200 names across several TLDs) can take minutes in one synchronous tool call; raise your client's tool timeout (Codex `tool_timeout_sec = 360`) before running one.
+
+### Environment variables
+
+| Variable | Required | Meaning |
+| --- | --- | --- |
+| `NAMING_SIGNAL_API_KEY` | Yes, for hosted tool calls | User API key created at https://namingsignal.com/developers/keys. Sent as the Authorization Bearer header, never logged. |
+| `NAMING_SIGNAL_API_URL` | No | API origin. Defaults to `https://namingsignal.com`; set `http://localhost:3000` when running the API locally. |
+
+## The five tools
+
+- `compile_project_brief`: turn a sentence, prompt, or README into a bounded, editable naming brief; missing fields stay explicit instead of being invented.
+- `create_naming_sprint`: generate and check 10 to 200 names across up to five TLDs, with feedback rounds (`feedback`, `likedNames`, `dislikedNames`, `existingNames`) and an optional full ledger (`includeLedger: true`).
+- `check_names`: exact domain registry evidence and optional npm/PyPI/GitHub/Apple namespace checks for up to 100 names.
+- `analyze_candidates`: deeper source-backed research for one to three finalists, with explicit unknowns and manual checks.
+- `get_purchase_links`: exact-domain registrar search links for manual verification; it never purchases or reserves anything.
+
+Tool output is compact by default; pass `verbose: true` only when full evidence objects are required.
+
+## Evidence honesty
+
+Registry RDAP not-found means likely unregistered at check time, not guaranteed registrability, registrar price, or trademark clearance. Timeout, rate limit, unsupported TLD, failed calibration, and missing research remain unknown and are never converted into available. Recheck every finalist at a registrar before purchase; naming research is not legal clearance.
+
+## License
+
+MIT, Copyright (c) 2026 Zena Labs LLC.

package/dist/agent-guidance.js

@@ -0,0 +1,7 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.AGENT_WORKFLOW_SUMMARY = void 0;
+// Vendored from the NamingSignal product source so the published stdio MCP
+// package stays self-contained. Keep this text in sync with the hosted agent
+// guide at https://namingsignal.com/agent-guide.txt.
+exports.AGENT_WORKFLOW_SUMMARY = `Use NamingSignal as an evidence-first workflow, not a one-shot name generator. Compile and inspect the brief before generation; correct material product, audience, pain, outcome, mechanism, channel, tone, future-scope, domain, and avoid constraints. Generate a broad field in distinct veins, preserve the ledger, bulk-check domains, check exact namespaces on survivors, and research only one to three finalists. When a founder gives feedback, preserve the approved brief, send liked and disliked examples as preference signals, exclude every prior name, and merge the checked new round into the same project ledger. Treat registry RDAP not-found only as likely unregistered. Timeout, rate limit, unsupported, failed calibration, ambiguity, and missing research remain unknown. Keep hard blockers and active same-category collisions separate from scores. Label deterministic fallback, overall score, and AI editorial rank accurately. Preserve sources, timestamps, evidence state, fallback/usage metadata, feedback rounds, rejections, and manual actions. Require current registrar verification, founder resonance, spoken-name testing when relevant, cultural review, and appropriate legal clearance. NamingSignal never purchases, reserves, files, contacts, or claims legal clearance.`;

package/dist/core/batch.js

@@ -0,0 +1,142 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.chunkItems = chunkItems;
+exports.classifyCandidate = classifyCandidate;
+exports.bestQualifyingDomain = bestQualifyingDomain;
+exports.sortCandidates = sortCandidates;
+const TAKEN_DOMAIN_STATES = new Set([
+    "registered",
+    "premium",
+    "parked",
+    "active",
+]);
+function normalizeTld(value) {
+    const normalized = value.trim().toLowerCase().replace(/^\.+|\.+$/g, "");
+    return /^[a-z0-9-]+$/.test(normalized) ? normalized : "";
+}
+function selectedTlds(values) {
+    const result = [];
+    const seen = new Set();
+    for (const value of values) {
+        const tld = normalizeTld(value);
+        if (!tld || seen.has(tld))
+            continue;
+        seen.add(tld);
+        result.push(tld);
+    }
+    return result;
+}
+function domainTld(domain) {
+    const labels = domain.trim().toLowerCase().replace(/\.$/, "").split(".");
+    return labels.length > 1 ? labels.at(-1) ?? "" : "";
+}
+function stateForTld(domains, tld) {
+    const states = new Set();
+    for (const domain of domains) {
+        if (domainTld(domain.domain) !== tld)
+            continue;
+        if (domain.status === "likely_available")
+            states.add("available");
+        else if (TAKEN_DOMAIN_STATES.has(domain.status))
+            states.add("taken");
+        else
+            states.add("review");
+    }
+    // Missing evidence and conflicting duplicate evidence both require review.
+    if (states.size !== 1)
+        return "review";
+    return states.values().next().value ?? "review";
+}
+function chunkItems(items, chunkSize) {
+    if (!Number.isSafeInteger(chunkSize) || chunkSize < 1) {
+        throw new RangeError("Chunk size must be a positive safe integer.");
+    }
+    const chunks = [];
+    for (let index = 0; index < items.length; index += chunkSize) {
+        chunks.push(items.slice(index, index + chunkSize));
+    }
+    return chunks;
+}
+/**
+ * Classify only against the selected TLDs. Unknown, unsupported, missing, or
+ * conflicting evidence never becomes available or taken by implication.
+ */
+function classifyCandidate(candidate, tlds, rule) {
+    const normalizedTlds = selectedTlds(tlds);
+    if (!normalizedTlds.length)
+        return "review";
+    const states = normalizedTlds.map((tld) => stateForTld(candidate.domains ?? [], tld));
+    if (rule === "any_selected") {
+        if (states.includes("available"))
+            return "available";
+        return states.every((state) => state === "taken") ? "taken" : "review";
+    }
+    if (rule === "all_selected") {
+        if (states.every((state) => state === "available"))
+            return "available";
+        return states.includes("taken") ? "taken" : "review";
+    }
+    throw new TypeError(`Unsupported availability rule: ${String(rule)}`);
+}
+/** Return the highest-priority selected domain that satisfies the rule. */
+function bestQualifyingDomain(candidate, tlds, rule = "any_selected") {
+    if (classifyCandidate(candidate, tlds, rule) !== "available")
+        return undefined;
+    const domains = candidate.domains ?? [];
+    for (const tld of selectedTlds(tlds)) {
+        const result = domains.find((domain) => domainTld(domain.domain) === tld && domain.status === "likely_available");
+        if (result)
+            return result;
+    }
+    return undefined;
+}
+function finiteScore(value) {
+    return typeof value === "number" && Number.isFinite(value) ? value : undefined;
+}
+function scoreForKey(score, key) {
+    if (!score)
+        return undefined;
+    if (key === "overall")
+        return finiteScore(score.overall);
+    return finiteScore(score.dimensions.find((dimension) => dimension.key === key)?.score);
+}
+function compareScoresDescending(left, right) {
+    if (left === undefined && right === undefined)
+        return 0;
+    if (left === undefined)
+        return 1;
+    if (right === undefined)
+        return -1;
+    return right - left;
+}
+/**
+ * Return a new deterministic ranking. The selected score descends first,
+ * followed by overall score, display name, and original order as the final
+ * stable tie-break.
+ */
+function sortCandidates(candidates, key = "overall") {
+    return candidates
+        .map((candidate, index) => ({ candidate, index }))
+        .sort((left, right) => {
+        const primary = compareScoresDescending(scoreForKey(left.candidate.score, key), scoreForKey(right.candidate.score, key));
+        if (primary)
+            return primary;
+        if (key !== "overall") {
+            const overall = compareScoresDescending(finiteScore(left.candidate.score?.overall), finiteScore(right.candidate.score?.overall));
+            if (overall)
+                return overall;
+        }
+        const insensitiveName = left.candidate.name.localeCompare(right.candidate.name, "en", {
+            numeric: true,
+            sensitivity: "base",
+        });
+        if (insensitiveName)
+            return insensitiveName;
+        const exactName = left.candidate.name.localeCompare(right.candidate.name, "en", {
+            numeric: true,
+            sensitivity: "variant",
+        });
+        return exactName || left.index - right.index;
+    })
+        .map(({ candidate }) => candidate);
+}

package/dist/core/brief-constraints.js

@@ -0,0 +1,72 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.explicitAvoidTerms = explicitAvoidTerms;
+exports.candidateAvoidViolations = candidateAvoidViolations;
+exports.candidateBriefConflicts = candidateBriefConflicts;
+const normalize_1 = require("./normalize");
+function explicitAvoidTerms(brief) {
+    if (!brief)
+        return [];
+    const terms = new Set();
+    for (const entry of brief.avoid) {
+        const normalized = (0, normalize_1.normalizeName)(entry);
+        const words = normalized.split(" ").filter(Boolean);
+        if (words.length <= 2 && normalized.length <= 28)
+            terms.add((0, normalize_1.comparisonKey)(normalized));
+        const examples = entry.match(/(?:such as|including|brands?\s*:?)\s+(.+)$/i)?.[1];
+        if (examples) {
+            for (const example of examples.split(/[,;/]|\band\b/i)) {
+                const key = (0, normalize_1.comparisonKey)(example);
+                if (key.length >= 3 && key.length <= 24)
+                    terms.add(key);
+            }
+        }
+    }
+    return [...terms].filter((term) => term.length >= 3);
+}
+function candidateAvoidViolations(name, brief) {
+    const key = (0, normalize_1.comparisonKey)(name);
+    return explicitAvoidTerms(brief).filter((term) => key.includes(term));
+}
+function candidateBriefConflicts(name, brief) {
+    if (!brief)
+        return { blockers: [], warnings: [], penalty: 0 };
+    const key = (0, normalize_1.comparisonKey)(name);
+    const context = (0, normalize_1.normalizeName)([
+        brief.product,
+        brief.pain,
+        brief.outcome,
+        brief.mechanism,
+        brief.futureExpansion,
+        ...brief.avoid,
+    ].join(" "));
+    const blockers = [];
+    const warnings = [];
+    let penalty = 0;
+    const avoided = candidateAvoidViolations(name, brief);
+    if (avoided.length) {
+        blockers.push(`${name} contains an explicitly avoided term: ${avoided.join(", ")}.`);
+    }
+    if (/\b(?:audio|audible|voice|announces|calls every rep|podcast|music)\b/.test(context) && /(?:inaudible|voiceless|muted)/.test(key)) {
+        blockers.push(`${name} contradicts the brief's audible-guidance mechanism.`);
+    }
+    if (/\b(?:finish|completion|purpose|useful|guided|carries the workout)\b/.test(context) && /(?:aimless|purposeless)/.test(key)) {
+        blockers.push(`${name} contradicts the brief's purposeful-completion outcome.`);
+    }
+    if (/\b(?:avoid|not aggressive|gym bro|punishment|negative)\b/.test(context) && /(?:mindless|gainz|shred|beast|crush|punish)/.test(key)) {
+        blockers.push(`${name} uses the negative or gym-bro language the brief excludes.`);
+    }
+    if (/\b(?:relief|without managing|low decision|mental overhead|autopilot)\b/.test(context) && /(?:tethered|trapped|bound)/.test(key)) {
+        warnings.push(`${name} implies restriction while the brief promises relief from micromanagement.`);
+        penalty += 18;
+    }
+    if (/\b(?:workout|exercise|reps|sets)\b/.test(context) && !/\b(?:cycling|bike|bicycle|ride)\b/.test(context) && /(?:pedal|bicycle|cycling)/.test(key)) {
+        warnings.push(`${name} suggests cycling even though the brief describes a broader workout product.`);
+        penalty += 22;
+    }
+    return {
+        blockers: [...new Set(blockers)],
+        warnings: [...new Set(warnings)],
+        penalty: Math.min(35, penalty),
+    };
+}