talentos 0.1.0 → 0.3.0

package/README.md

@@ -3,7 +3,10 @@
 A thin [stdio MCP](https://modelcontextprotocol.io) server that wraps the TalentOS
 external HTTP API (`/api/v0/*`). Point any MCP-capable agent (Claude Code, Claude
 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.
+nodes, then create or replace its own private Skills 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:
 
@@ -17,14 +20,14 @@ It exposes six tools:
   agent-ready Markdown runbook, including its `**Version:**` stamp.
 - **`list_nodes`** (no arguments) — company-wide reusable nodes as name, id,
   step type, summary, and tools.
-- **`create_workflow`** (`{ title, steps, connections }`) — create a new draft
-  workflow from a full plan. Steps may include `outputs`, `successCriteria`, and
-  `runtime` contract fields. Writes always create drafts; a human publishes in
-  the app.
-- **`update_workflow`** (`{ workflowId, title, steps, connections }`) —
-  replace an existing draft workflow from a full plan. Steps may include
-  `outputs`, `successCriteria`, and `runtime`; published workflows return a
-  clear conflict instead of being edited.
+- **`create_skill`** (`{ name, summary, instructions, successCriteria?,
+  requestedTools? }`) — create a new Skill from plain-text instructions.
+  Returns the new `skillId` and its version. The Skill is private to the API
+  key's owner, who curates it in their TalentOS Skills library.
+- **`update_skill`** (`{ skillId, name, summary, instructions,
+  successCriteria?, requestedTools? }`) — replace one of the API key owner's
+  private Skills with a complete new body. Only that owner's private Skills are
+  writable; published and shared Skills stay human-owned.
 
 The server holds no state and stores nothing. Every call is a single
 authenticated request to the HTTP API; all authorization and visibility rules
@@ -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.3.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,23 +104,22 @@ 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:
+4. **Ask the agent** to list your workflows, then create a Skill:
 
    > List my TalentOS workflows, show me the first one as markdown, then create
-   > a new draft workflow for candidate outreach.
+   > a Skill for candidate outreach.
 
-   The agent calls `list_workflows`, `get_workflow`, and `create_workflow`. The
-   new workflow lands as a draft in TalentOS for a human to review and publish.
+   The agent calls `list_workflows`, `get_workflow`, and `create_skill`. The new
+   Skill lands as a private Skill in TalentOS for its owner to review.
 
 ## Errors you might see
 
 - **Unauthorized (401)** — `TALENTOS_API_KEY` is missing, wrong, or revoked.
-- **Workflow not found (404)** — the `id` doesn't exist or it is not visible to
-  this API key.
-- **Published workflow conflict (409)** — `update_workflow` only edits drafts;
-  published workflows must be duplicated or edited in TalentOS.
+- **Not found (404)** — the workflow or skill `id` doesn't exist, or it is not
+  visible to this API key. `update_skill` only reaches the key owner's own
+  private Skills.
 - **Rate limited (429)** — the key is over its requests-per-minute budget;
   wait a moment and retry.
 - **Could not reach the API** — `TALENTOS_API_URL` is wrong or unreachable;

package/dist/api.js

@@ -7,6 +7,7 @@
 const WORKFLOWS_PATH = "/api/v0/workflows";
 const NODES_PATH = "/api/v0/nodes";
 const CONTEXT_PATH = "/api/v0/context";
+const SKILLS_PATH = "/api/v0/skills";
 // A hung deployment (connection accepted, no response) would otherwise leave the
 // tool call pending forever with no error; abort so it surfaces as networkError.
 const REQUEST_TIMEOUT_MS = 15_000;
@@ -15,11 +16,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 +73,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.");
     }
@@ -102,24 +99,24 @@ export async function getContext(config) {
     // formatting opinion belongs server-side, not in this wrapper.
     return textResult(JSON.stringify(result.body, null, 2));
 }
-export async function createWorkflow(config, plan) {
-    return await writeWorkflow(config, WORKFLOWS_PATH, plan, "Created");
+export async function createSkill(config, skill) {
+    return await writeSkill(config, SKILLS_PATH, skill, "Created");
 }
-export async function updateWorkflow(config, workflowId, plan) {
-    return await writeWorkflow(config, `${WORKFLOWS_PATH}/${encodeURIComponent(workflowId)}`, plan, "Updated", workflowId);
+export async function updateSkill(config, skillId, skill) {
+    return await writeSkill(config, `${SKILLS_PATH}/${encodeURIComponent(skillId)}`, skill, "Updated", skillId);
 }
 const URL_HINT = "The TALENTOS_API_URL may be wrong — it must point at the deployment's https://<name>.convex.site domain.";
-async function writeWorkflow(config, path, plan, action, workflowId) {
-    const result = await fetchJson(config, path, path === WORKFLOWS_PATH ? "POST" : "PUT", plan, workflowId);
+async function writeSkill(config, path, skill, action, skillId) {
+    const result = await fetchJson(config, path, path === SKILLS_PATH ? "POST" : "PUT", skill);
     if ("error" in result) {
         return result.error;
     }
-    const id = result.body.id ?? workflowId;
-    const status = result.body.status ?? "draft";
-    if (!id) {
-        return toolError(`The response was missing a workflow id. ${URL_HINT}`);
+    const id = result.body.skillId ?? skillId;
+    const version = result.body.version;
+    if (!id || version === undefined) {
+        return toolError(`The response was missing a skill id or version. ${URL_HINT}`);
     }
-    return textResult(`${action} workflow draft (id: ${id}) · status: ${status}\nA human must publish it in TalentOS.`);
+    return textResult(`${action} skill (id: ${id}) · version ${version}\nPrivate to this API key's owner; they curate it in their TalentOS Skills library.`);
 }
 function textResult(text) {
     return { content: [{ text, type: "text" }] };
@@ -140,7 +137,7 @@ async function httpError(response, workflowId) {
     }
     if (response.status === 409) {
         return toolError(message ??
-            "This workflow is published and can't be edited through the API.");
+            "This write conflicts with the current state. Reload and retry.");
     }
     if (response.status === 429) {
         return toolError("Rate limited (429). This API key is over its requests-per-minute budget — wait a moment and retry.");

package/dist/index.js

@@ -5,75 +5,32 @@
 import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
 import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
 import { z } from "zod";
-import { createWorkflow, getContext, getWorkflow, listNodes, listWorkflows, updateWorkflow, } from "./api.js";
+import { createSkill, getContext, getWorkflow, listNodes, listWorkflows, updateSkill, } from "./api.js";
 const TRAILING_SLASHES = /\/+$/;
-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."),
-    stepType: z.enum(["human", "ai_assisted", "ai_agent", "automation"]),
-    description: z
+// 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 SKILL_SCHEMA = {
+    instructions: z
         .string()
-        .optional()
-        .describe("Complete markdown instructions for the step."),
-    dataNeeded: z
-        .array(z.object({
-        label: z.string().describe("Short input name."),
-        detail: z
-            .string()
-            .optional()
-            .describe("Optional detail about the input."),
-    }))
-        .optional()
-        .describe("Inputs the step needs."),
-    outputs: z
-        .array(z.object({
-        label: z.string().describe("Artifact or deliverable name."),
-        detail: z
-            .string()
-            .optional()
-            .describe("Optional detail about the output."),
-        format: z
-            .string()
-            .optional()
-            .describe("Optional format hint, such as markdown, json, or url."),
-    }))
-        .optional()
-        .describe("Artifacts or deliverables the step produces."),
-    successCriteria: z
-        .string()
-        .optional()
-        .describe("How a reviewer or agent knows this step is done well."),
-    runtime: z
-        .object({
-        kind: z
-            .string()
-            .describe('Runtime the user named, such as "claude-code" or "api".'),
-        model: z.string().optional().describe("Optional model name."),
-        config: z
-            .record(z.string(), z.string())
-            .optional()
-            .describe("Optional string config for the runtime."),
-    })
-        .optional()
-        .describe("What executes this step, when the user names a runtime."),
-    toolNames: z
+        .describe("Complete plain-text instructions for the Skill."),
+    name: z.string().describe("Short title for the Skill."),
+    requestedTools: z
         .array(z.string())
         .optional()
         .describe("Tool names exactly as the user named them."),
-});
-const WORKFLOW_CONNECTION_SCHEMA = z.object({
-    fromKey: z.string().describe("The source step key."),
-    toKey: z.string().describe("The target step key."),
-    label: z
+    successCriteria: z
         .string()
         .optional()
-        .describe("Short branch label, only when the flow branches."),
-});
+        .describe("How a reviewer knows the Skill did its job well."),
+    summary: z.string().describe("One-sentence summary of what the Skill does."),
+};
 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",
@@ -96,62 +53,47 @@ async function main() {
         title: "Get org context",
         description: "One compact summary of the org this API key belongs to: company profile basics plus the names of its published workflows and nodes. Call this first to prime yourself.",
     }, () => getContext(config));
-    server.registerTool("create_workflow", {
-        title: "Create workflow draft",
-        description: "Create a new TalentOS workflow draft from a full title/steps/connections plan. Steps may include agent contract fields: outputs, successCriteria, and runtime. Writes always create drafts that a human publishes in the app.",
-        inputSchema: {
-            title: z.string().describe("Short name for the whole workflow."),
-            steps: z
-                .array(WORKFLOW_STEP_SCHEMA)
-                .describe("The ordered workflow steps to materialize."),
-            connections: z
-                .array(WORKFLOW_CONNECTION_SCHEMA)
-                .optional()
-                .describe("Directed edges between the steps. Omit for no edges."),
-        },
-    }, ({ connections, steps, title }) => createWorkflow(config, {
-        connections: connections ?? [],
-        steps,
-        title,
+    server.registerTool("create_skill", {
+        title: "Create Skill",
+        description: "Create a new private TalentOS Skill from a name, summary, instructions, and success criteria. The Skill is private to the API key's owner, who curates it in TalentOS.",
+        inputSchema: SKILL_SCHEMA,
+    }, ({ instructions, name, requestedTools, successCriteria, summary }) => createSkill(config, {
+        instructions,
+        name,
+        ...(requestedTools === undefined ? {} : { requestedTools }),
+        ...(successCriteria === undefined ? {} : { successCriteria }),
+        summary,
     }));
-    server.registerTool("update_workflow", {
-        title: "Replace workflow draft",
-        description: "Replace an existing TalentOS workflow draft with a full title/steps/connections plan. Steps may include agent contract fields: outputs, successCriteria, and runtime. Drafts only: updating a published workflow returns a clear conflict message.",
+    server.registerTool("update_skill", {
+        title: "Replace Skill",
+        description: "Replace the API key owner's private TalentOS Skill with a complete name, summary, instructions, and success criteria.",
         inputSchema: {
-            workflowId: z.string().describe("The workflow id from list_workflows."),
-            title: z.string().describe("Short name for the whole workflow."),
-            steps: z
-                .array(WORKFLOW_STEP_SCHEMA)
-                .describe("The complete replacement step list."),
-            connections: z
-                .array(WORKFLOW_CONNECTION_SCHEMA)
-                .optional()
-                .describe("The complete replacement edge list. Omit for no edges."),
+            skillId: z.string().describe("The skill id from create_skill."),
+            ...SKILL_SCHEMA,
         },
-    }, ({ connections, steps, title, workflowId }) => updateWorkflow(config, workflowId, {
-        connections: connections ?? [],
-        steps,
-        title,
+    }, ({ instructions, name, requestedTools, skillId, successCriteria, summary, }) => updateSkill(config, skillId, {
+        instructions,
+        name,
+        ...(requestedTools === undefined ? {} : { requestedTools }),
+        ...(successCriteria === undefined ? {} : { successCriteria }),
+        summary,
     }));
     await server.connect(new StdioServerTransport());
 }
 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,9 +1,8 @@
 {
   "name": "talentos",
-  "version": "0.1.0",
-  "license": "MIT",
+  "version": "0.3.0",
   "type": "module",
-  "description": "Stdio MCP server wrapping the TalentOS external HTTP API for workflow reads and draft writes.",
+  "description": "Stdio MCP server wrapping the TalentOS external HTTP API for workflow reads and private Skill writes.",
   "bin": {
     "talentos": "./dist/index.js"
   },
@@ -15,17 +14,17 @@
   },
   "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",
     "zod": "^4.4.3"
   },
   "devDependencies": {
-    "@types/node": "^26.1.0",
-    "tsx": "^4.22.5",
+    "@types/node": "^22",
+    "tsx": "^4.21.0",
     "typescript": "^6.0.3"
   }
 }

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.