talentos 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+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.

package/README.md

@@ -0,0 +1,148 @@
+# talentos
+
+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.
+
+It exposes six tools:
+
+- **`get_context`** (no arguments) — one compact org summary: company profile
+  basics plus the names of the org's published workflows and nodes.
+  Good first call to prime an agent.
+- **`list_workflows`** (no arguments) — published workflows plus drafts created
+  by the API key's owner as a compact text list (status, title, id, step count,
+  department, description, ISO `updatedAt`).
+- **`get_workflow`** (`{ workflowId: string }`) — one workflow as an
+  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.
+
+The server holds no state and stores nothing. Every call is a single
+authenticated request to the HTTP API; all authorization and visibility rules
+live server-side.
+
+## Configuration
+
+Two environment variables, both required. The server exits immediately with a
+message on stderr if either is missing.
+
+| 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`. |
+
+## 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:
+
+```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).
+
+## 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
+```
+
+Then ask Claude Code to *"list our TalentOS workflows and show me one as
+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:
+
+```json
+{
+  "mcpServers": {
+    "talentos": {
+      "command": "npx",
+      "args": ["-y", "talentos"],
+      "env": {
+        "TALENTOS_API_KEY": "tos_your_key_here",
+        "TALENTOS_API_URL": "https://your-deployment.convex.site"
+      }
+    }
+  }
+}
+```
+
+## Five-minute smoke test
+
+1. **Create a key.** In the TalentOS admin UI, create an API key. Copy the
+   `tos_...` value (you only see it once).
+
+2. **Curl the list endpoint** to confirm the key and URL work before involving an
+   agent:
+
+   ```bash
+   curl -H "Authorization: Bearer tos_your_key_here" \
+     https://your-deployment.convex.site/api/v0/workflows
+   ```
+
+   You should get `{ "workflows": [ ... ] }`. A `401` means the key is wrong;
+   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.
+
+4. **Ask the agent** to list your workflows, then create a draft:
+
+   > List my TalentOS workflows, show me the first one as markdown, then create
+   > a new draft workflow 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.
+
+## 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.
+- **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;
+  confirm it is the `.convex.site` URL.

package/dist/api.js

@@ -0,0 +1,213 @@
+// The HTTP-client half of the MCP server: one function per TalentOS
+// /api/v0/* endpoint, returning MCP-shaped text results. Deliberately free of
+// MCP SDK imports (ToolResult is structurally CallToolResult-compatible) so
+// these handlers unit-test from the repo root against a mocked fetch without
+// installing this package's dependencies. Zero business logic lives here —
+// authz, org scoping, and visibility are all server-side.
+const WORKFLOWS_PATH = "/api/v0/workflows";
+const NODES_PATH = "/api/v0/nodes";
+const CONTEXT_PATH = "/api/v0/context";
+// 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;
+export async function listWorkflows(config) {
+    const result = await fetchJson(config, WORKFLOWS_PATH);
+    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
+        : [];
+    if (workflows.length === 0) {
+        return textResult("No workflows are visible to this API key.");
+    }
+    const lines = workflows.map((workflow) => {
+        const parts = [
+            `- ${workflow.title} (id: ${workflow.id})`,
+            `status: ${workflow.status}`,
+            `${workflow.stepCount} step(s)`,
+            `dept: ${workflow.department ?? "—"}`,
+            `updated ${workflow.updatedAt ?? "unknown"}`,
+        ];
+        if (workflow.description) {
+            parts.push(workflow.description);
+        }
+        return parts.join(" · ");
+    });
+    return textResult(`${workflows.length} workflow(s):\n${lines.join("\n")}`);
+}
+export async function getWorkflow(config, workflowId) {
+    const url = `${config.baseUrl}${WORKFLOWS_PATH}/${encodeURIComponent(workflowId)}`;
+    let response;
+    try {
+        response = await fetch(url, {
+            headers: {
+                Accept: "text/markdown",
+                Authorization: `Bearer ${config.apiKey}`,
+            },
+            signal: AbortSignal.timeout(REQUEST_TIMEOUT_MS),
+        });
+    }
+    catch (error) {
+        return networkError(error);
+    }
+    if (!response.ok) {
+        return await httpError(response, workflowId);
+    }
+    // The wrong-URL failure mode is a login page or JSON error served from the
+    // wrong domain; a rewritten/stripped content-type on a real runbook is not.
+    // Reject only the clearly-wrong types so a text/plain runbook still passes.
+    const contentType = (response.headers.get("content-type") ?? "").toLowerCase();
+    if (contentType.includes("text/html") ||
+        contentType.includes("application/json")) {
+        return toolError(`Expected a Markdown runbook but got content-type "${contentType || "unknown"}". ${URL_HINT}`);
+    }
+    try {
+        return textResult(await response.text());
+    }
+    catch (error) {
+        return networkError(error);
+    }
+}
+export async function listNodes(config) {
+    const result = await fetchJson(config, NODES_PATH);
+    if ("error" in result) {
+        return result.error;
+    }
+    const nodes = Array.isArray(result.body.nodes) ? result.body.nodes : [];
+    if (nodes.length === 0) {
+        return textResult("No company nodes are published.");
+    }
+    const lines = nodes.map((node) => {
+        const parts = [
+            `- ${node.name} (id: ${node.id})`,
+            node.stepType,
+            node.summary,
+        ];
+        if (Array.isArray(node.toolNames) && node.toolNames.length > 0) {
+            parts.push(`tools: ${node.toolNames.join(", ")}`);
+        }
+        return parts.join(" · ");
+    });
+    return textResult(`${nodes.length} node(s):\n${lines.join("\n")}`);
+}
+export async function getContext(config) {
+    const result = await fetchJson(config, CONTEXT_PATH);
+    if ("error" in result) {
+        return result.error;
+    }
+    // The org summary as-is: it is already a compact priming payload, and any
+    // 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 updateWorkflow(config, workflowId, plan) {
+    return await writeWorkflow(config, `${WORKFLOWS_PATH}/${encodeURIComponent(workflowId)}`, plan, "Updated", workflowId);
+}
+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);
+    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}`);
+    }
+    return textResult(`${action} workflow draft (id: ${id}) · status: ${status}\nA human must publish it in TalentOS.`);
+}
+function textResult(text) {
+    return { content: [{ text, type: "text" }] };
+}
+function toolError(text) {
+    return { content: [{ text, type: "text" }], isError: true };
+}
+async function httpError(response, workflowId) {
+    const { message } = await parseErrorBody(response);
+    if (response.status === 400 && message) {
+        return toolError(message);
+    }
+    if (response.status === 401) {
+        return toolError("Unauthorized (401). Check that TALENTOS_API_KEY is a valid, active key for this deployment.");
+    }
+    if (response.status === 404 && workflowId) {
+        return toolError(`No workflow with id "${workflowId}" exists, or it is not visible to this API key.`);
+    }
+    if (response.status === 409) {
+        return toolError(message ??
+            "This workflow is published and can't be edited through the API.");
+    }
+    if (response.status === 429) {
+        return toolError("Rate limited (429). This API key is over its requests-per-minute budget — wait a moment and retry.");
+    }
+    if (message) {
+        return toolError(`The TalentOS API returned ${response.status}: ${message}`);
+    }
+    return toolError(`The TalentOS API returned an unexpected status ${response.status}.`);
+}
+async function parseErrorBody(response) {
+    const contentType = (response.headers.get("content-type") ?? "").toLowerCase();
+    if (!contentType.includes("application/json")) {
+        return {};
+    }
+    try {
+        const body = await response.json();
+        if (typeof body === "object" &&
+            body !== null &&
+            typeof body.error === "string") {
+            return { message: body.error };
+        }
+    }
+    catch {
+        return {};
+    }
+    return {};
+}
+async function fetchJson(config, path, method = "GET", body, workflowId) {
+    let response;
+    try {
+        response = await fetch(`${config.baseUrl}${path}`, {
+            body: body === undefined ? undefined : JSON.stringify(body),
+            headers: {
+                Accept: "application/json",
+                Authorization: `Bearer ${config.apiKey}`,
+                ...(body === undefined ? {} : { "Content-Type": "application/json" }),
+            },
+            method,
+            signal: AbortSignal.timeout(REQUEST_TIMEOUT_MS),
+        });
+    }
+    catch (error) {
+        return { error: networkError(error) };
+    }
+    if (!response.ok) {
+        return { error: await httpError(response, workflowId) };
+    }
+    let parsed;
+    try {
+        parsed = await response.json();
+    }
+    catch {
+        return {
+            error: toolError(`The response was not valid JSON. ${URL_HINT}`),
+        };
+    }
+    if (parsed === null || typeof parsed !== "object") {
+        return {
+            error: toolError(`The response was not a JSON object. ${URL_HINT}`),
+        };
+    }
+    return { body: parsed };
+}
+function networkError(error) {
+    if (error instanceof Error && error.name === "TimeoutError") {
+        return toolError(`The TalentOS API did not respond within ${REQUEST_TIMEOUT_MS / 1000}s. The deployment may be overloaded or unreachable — check TALENTOS_API_URL and retry.`);
+    }
+    const detail = error instanceof Error ? error.message : String(error);
+    return toolError(`Could not reach the TalentOS API. Check TALENTOS_API_URL points at the deployment's .convex.site domain. (${detail})`);
+}

package/dist/index.js

@@ -0,0 +1,157 @@
+#!/usr/bin/env node
+// Stdio MCP server wrapping the TalentOS external HTTP API — the MCP wiring
+// only. The tool handlers live in api.ts (pure fetch wrappers) so they
+// unit-test without this file's SDK dependencies.
+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";
+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
+        .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
+        .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
+        .string()
+        .optional()
+        .describe("Short branch label, only when the flow branches."),
+});
+async function main() {
+    const config = loadConfig();
+    const server = new McpServer({
+        name: "talentos",
+        version: "0.1.0",
+    });
+    server.registerTool("list_workflows", {
+        title: "List workflows",
+        description: "List the TalentOS workflows visible to this API key: published workflows plus drafts created by the key's owner. Returns status, title, id, step count, department, and description for each so you can pick one to fetch or update.",
+    }, () => listWorkflows(config));
+    server.registerTool("get_workflow", {
+        title: "Get workflow",
+        description: "Fetch a single visible TalentOS workflow as an agent-ready Markdown runbook. Pass the workflow id from list_workflows.",
+        inputSchema: {
+            workflowId: z
+                .string()
+                .describe("The workflow id, as returned by list_workflows."),
+        },
+    }, ({ workflowId }) => getWorkflow(config, workflowId));
+    server.registerTool("list_nodes", {
+        title: "List nodes",
+        description: "List the org's company-wide TalentOS nodes (reusable, admin-promoted workflow steps). Returns name, id, step type, and summary for each.",
+    }, () => listNodes(config));
+    server.registerTool("get_context", {
+        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("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.",
+        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."),
+        },
+    }, ({ connections, steps, title, workflowId }) => updateWorkflow(config, workflowId, {
+        connections: connections ?? [],
+        steps,
+        title,
+    }));
+    await server.connect(new StdioServerTransport());
+}
+function loadConfig() {
+    const apiKey = process.env.TALENTOS_API_KEY?.trim();
+    const rawUrl = process.env.TALENTOS_API_URL?.trim();
+    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.exit(1);
+}
+main().catch((error) => {
+    const detail = error instanceof Error ? error.message : String(error);
+    process.stderr.write(`[talentos] fatal: ${detail}\n`);
+    process.exit(1);
+});

package/package.json

@@ -0,0 +1,31 @@
+{
+  "name": "talentos",
+  "version": "0.1.0",
+  "license": "MIT",
+  "type": "module",
+  "description": "Stdio MCP server wrapping the TalentOS external HTTP API for workflow reads and draft writes.",
+  "bin": {
+    "talentos": "./dist/index.js"
+  },
+  "files": [
+    "dist"
+  ],
+  "engines": {
+    "node": ">=18"
+  },
+  "scripts": {
+    "start": "tsx src/index.ts",
+    "build": "tsc -p tsconfig.build.json",
+    "typecheck": "tsc --noEmit",
+    "prepack": "npm run build"
+  },
+  "dependencies": {
+    "@modelcontextprotocol/sdk": "^1.29.0",
+    "zod": "^4.4.3"
+  },
+  "devDependencies": {
+    "@types/node": "^26.1.0",
+    "tsx": "^4.22.5",
+    "typescript": "^6.0.3"
+  }
+}