talentos 0.1.0 → 0.2.0

package/README.md

@@ -5,6 +5,9 @@ external HTTP API (`/api/v0/*`). Point any MCP-capable agent (Claude Code, Claud
 Desktop, Cursor, etc.) at it and the agent can read your org's workflows and
 nodes, then create or replace workflow drafts through the same API key.
 
+Published to npm as [`talentos`](https://www.npmjs.com/package/talentos) — run it
+with `npx -y talentos`, no checkout or build required.
+
 It exposes six tools:
 
 - **`get_context`** (no arguments) — one compact org summary: company profile
@@ -32,56 +35,34 @@ live server-side.
 
 ## Configuration
 
-Two environment variables, both required. The server exits immediately with a
-message on stderr if either is missing.
+Only `TALENTOS_API_KEY` is required — the server exits immediately with a message
+on stderr if it's missing. `TALENTOS_API_URL` is optional: it defaults to the
+production TalentOS deployment, so most users never set it.
 
 | Variable            | Required | Description                                                                                                   |
 | ------------------- | -------- | ------------------------------------------------------------------------------------------------------------- |
 | `TALENTOS_API_KEY`  | yes      | An API key you create in the TalentOS admin UI. Sent as `Authorization: Bearer <key>`. Never logged.          |
-| `TALENTOS_API_URL`  | yes      | The deployment's **`https://<name>.convex.site`** base URL — the `.convex.site` domain, **not** `.convex.cloud`. |
+| `TALENTOS_API_URL`  | no       | Override the API base URL to target a non-production deployment. Defaults to the production `https://<name>.convex.site` origin. Must be the `.convex.site` domain, **not** `.convex.cloud`. |
 
 ## Install
 
-Run the server with `npx` — no clone or build required. Your MCP client
-launches it on demand; `npx` fetches and caches `talentos` on first use:
+Nothing to install ahead of time — `npx` fetches the published package on first
+run and caches it:
 
 ```bash
 npx -y talentos
 ```
 
-Set the two environment variables above in your MCP client config (snippets
-below), not on the command line. The `-y` flag skips npx's install prompt so it
-also works in noninteractive clients.
-
-### Run from source (contributors)
-
-Working on the server itself? It keeps its own dependencies and lockfile — the
-repo-root `pnpm install` does **not** install them. Once per clone:
-
-```bash
-cd tools/mcp-server && pnpm install --ignore-workspace
-```
-
-(`--ignore-workspace` keeps it out of the root lockfile — this package is
-deliberately not part of the app workspace.) To point a client at your
-checkout, set `command` to the package-local tsx binary
-(`tools/mcp-server/node_modules/.bin/tsx`) and `args` to `src/index.ts`, both
-as absolute paths. Two launch paths that look equivalent are not:
-
-- `npx tsx …` resolves `tsx` on demand, so a client machine without it cached
-  does a network fetch at launch — in a noninteractive or offline MCP client
-  this fails (`ENOTCACHED`).
-- `pnpm start` prints its script banner to **stdout**, which corrupts the MCP
-  JSON-RPC stream (`pnpm --silent` avoids it, but the plain form is a trap).
+The `-y` skips the install prompt so noninteractive MCP clients don't hang. The
+first launch does a one-time network fetch to populate the npx cache (then exits
+asking for `TALENTOS_API_KEY`); run it once by hand — or pin a version like
+`talentos@0.2.0` — before wiring it into an offline or CI environment.
 
 ## Add it to Claude Code
 
-From anywhere — npx fetches the package, so no checkout is needed:
-
 ```bash
 claude mcp add talentos \
   -e TALENTOS_API_KEY=tos_your_key_here \
-  -e TALENTOS_API_URL=https://your-deployment.convex.site \
   -- npx -y talentos
 ```
 
@@ -90,8 +71,7 @@ markdown"* — it calls `list_workflows`, picks an id, and calls `get_workflow`.
 
 ## Add it to any other MCP client
 
-Add this to your MCP client config (`.mcp.json`, Claude Desktop config, etc.).
-`npx` resolves and caches the package, so there are no repo paths to wire up:
+Add this to your MCP client config (`.mcp.json`, Claude Desktop config, etc.):
 
 ```json
 {
@@ -100,8 +80,7 @@ Add this to your MCP client config (`.mcp.json`, Claude Desktop config, etc.).
       "command": "npx",
       "args": ["-y", "talentos"],
       "env": {
-        "TALENTOS_API_KEY": "tos_your_key_here",
-        "TALENTOS_API_URL": "https://your-deployment.convex.site"
+        "TALENTOS_API_KEY": "tos_your_key_here"
       }
     }
   }
@@ -125,7 +104,7 @@ Add this to your MCP client config (`.mcp.json`, Claude Desktop config, etc.).
    make sure you used the `.convex.site` domain, not `.convex.cloud`.
 
 3. **Add the server** to your MCP client using a snippet above, with your real
-   key and URL.
+   key (the API URL defaults to production).
 
 4. **Ask the agent** to list your workflows, then create a draft:
 

package/dist/api.js

@@ -15,11 +15,7 @@ export async function listWorkflows(config) {
     if ("error" in result) {
         return result.error;
     }
-    // A wrong-URL proxy or shape drift can return a non-array here; treat that
-    // like the other malformed-response cases instead of throwing on .map.
-    const workflows = Array.isArray(result.body.workflows)
-        ? result.body.workflows
-        : [];
+    const workflows = result.body.workflows ?? [];
     if (workflows.length === 0) {
         return textResult("No workflows are visible to this API key.");
     }
@@ -76,7 +72,7 @@ export async function listNodes(config) {
     if ("error" in result) {
         return result.error;
     }
-    const nodes = Array.isArray(result.body.nodes) ? result.body.nodes : [];
+    const nodes = result.body.nodes ?? [];
     if (nodes.length === 0) {
         return textResult("No company nodes are published.");
     }

package/dist/index.js

@@ -7,6 +7,10 @@ import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js"
 import { z } from "zod";
 import { createWorkflow, getContext, getWorkflow, listNodes, listWorkflows, updateWorkflow, } from "./api.js";
 const TRAILING_SLASHES = /\/+$/;
+// The production TalentOS API origin. The server defaults to it so users only
+// need to supply TALENTOS_API_KEY; set TALENTOS_API_URL to override (e.g. a dev
+// deployment). Must be the .convex.site HTTP-action domain, not .convex.cloud.
+const DEFAULT_API_URL = "https://woozy-oyster-769.convex.site";
 const WORKFLOW_STEP_SCHEMA = z.object({
     key: z.string().describe("Short kebab-case slug, unique per step."),
     title: z.string().describe("Short imperative phrase, at most 8 words."),
@@ -73,7 +77,7 @@ async function main() {
     const config = loadConfig();
     const server = new McpServer({
         name: "talentos",
-        version: "0.1.0",
+        version: "0.0.0",
     });
     server.registerTool("list_workflows", {
         title: "List workflows",
@@ -137,21 +141,18 @@ async function main() {
 }
 function loadConfig() {
     const apiKey = process.env.TALENTOS_API_KEY?.trim();
-    const rawUrl = process.env.TALENTOS_API_URL?.trim();
+    const rawUrl = process.env.TALENTOS_API_URL?.trim() || DEFAULT_API_URL;
     if (!apiKey) {
         exitWithConfigError("TALENTOS_API_KEY is not set. Create an API key in the TalentOS admin UI and pass it via the env block of your MCP client config.");
     }
-    if (!rawUrl) {
-        exitWithConfigError("TALENTOS_API_URL is not set. It must be the deployment's https://<name>.convex.site URL (not .convex.cloud).");
-    }
     return { apiKey, baseUrl: rawUrl.replace(TRAILING_SLASHES, "") };
 }
 function exitWithConfigError(message) {
-    process.stderr.write(`[talentos] ${message}\n`);
+    process.stderr.write(`[talentos-mcp] ${message}\n`);
     process.exit(1);
 }
 main().catch((error) => {
     const detail = error instanceof Error ? error.message : String(error);
-    process.stderr.write(`[talentos] fatal: ${detail}\n`);
+    process.stderr.write(`[talentos-mcp] fatal: ${detail}\n`);
     process.exit(1);
 });

package/package.json

@@ -1,7 +1,6 @@
 {
   "name": "talentos",
-  "version": "0.1.0",
-  "license": "MIT",
+  "version": "0.2.0",
   "type": "module",
   "description": "Stdio MCP server wrapping the TalentOS external HTTP API for workflow reads and draft writes.",
   "bin": {
@@ -15,9 +14,9 @@
   },
   "scripts": {
     "start": "tsx src/index.ts",
-    "build": "tsc -p tsconfig.build.json",
+    "build": "rm -rf dist && tsc -p tsconfig.build.json",
     "typecheck": "tsc --noEmit",
-    "prepack": "npm run build"
+    "prepack": "rm -rf dist && tsc -p tsconfig.build.json"
   },
   "dependencies": {
     "@modelcontextprotocol/sdk": "^1.29.0",

package/LICENSE

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