@anyknown/mcp 0.1.3

package/README.md

@@ -0,0 +1,34 @@
+# anyknown/mcp
+
+The MCP hub: the directory of MCP servers (admin catalogue plus each user's own `own_*` servers), the MCP client, OAuth (discovery, dynamic registration, PKCE, refresh), per-user credentials and the tool cache.
+
+It has no public URL. The only way in is product's `MCP` service binding, which calls the `Hub` `WorkerEntrypoint` over RPC (`src/rpc/`). Product owns authentication, scope checks (`mcp:use`, `product:admin`), request validation, activity and the OAuth cookie; the hub trusts the `userId` product passes.
+
+Tokens are sealed to the user's public key and opened only through product's `KeyringMcp` entrypoint (`KEYRING`, a service binding to `product` / `product-staging` that exposes only `seal` / `open` for kind `mcp`), so that entrypoint has to be deployed before this worker. A locked Keyring is `key_locked` (423); a user with no public key yet is `no_user_key` (409).
+
+## Environments
+
+|            | Worker        | D1            | `PRODUCT_BASE_URL`                 |
+| ---------- | ------------- | ------------- | ---------------------------------- |
+| production | `mcp`         | `mcp`         | `https://app.anyknown.com`         |
+| staging    | `mcp-staging` | `mcp-staging` | `https://staging-app.anyknown.com` |
+
+`PRODUCT_BASE_URL` is product's app host, not the hub's: the OAuth `redirect_uri` (`/api/mcp/callback`) and client id (`/api/mcp/client-metadata`) live there.
+
+## Dev
+
+```sh
+pnpm install
+cp .dev.vars.example .dev.vars
+pnpm dev
+```
+
+Product's `pnpm dev` starts this worker alongside it (`-c ../../../mcp/wrangler.jsonc`), so the `MCP` binding resolves locally. `pnpm check` runs typecheck, oxlint and oxfmt; `pnpm test` runs the workerd tests.
+
+## Secrets
+
+GitHub Actions needs `CLOUDFLARE_API_TOKEN` and `CLOUDFLARE_ACCOUNT_ID`.
+
+## Deploy
+
+Only through GitHub Actions. A push to `main` runs `check.yml`; when it is green its `staging` job migrates `mcp-staging` and deploys `mcp-staging`. Production is the manual `deploy.yml` (environment `production`, `main` only): migrate `mcp`, then deploy `mcp`.

package/dist/catalog/types.d.ts

@@ -0,0 +1,21 @@
+import type { McpServerRow, McpToolRow } from "../schema";
+export type CatalogServer = McpServerRow & {
+    tool_count: number;
+};
+export type ServerSummary = McpServerRow & {
+    connected: number;
+    tool_count: number;
+    synced_at: number | null;
+};
+export type ToolHit = {
+    tool: string;
+    title?: string;
+    description: string;
+};
+export type HitRow = {
+    server_id: string;
+    name: string;
+    title: string | null;
+    description: string;
+};
+export type ToolListing = Pick<McpToolRow, "name" | "title" | "description" | "annotations">;

package/dist/errors.d.ts

@@ -0,0 +1,16 @@
+export type AuthChallenge = {
+    resourceMetadata: string | null;
+    scope: string | null;
+};
+export type McpErrorCode = "invalid" | "not_found" | "mcp_not_connected" | "mcp_upstream_error" | "no_user_key" | "key_locked";
+export declare class McpError extends Error {
+    readonly code: McpErrorCode;
+    readonly status: 400 | 404 | 409 | 412 | 423 | 502;
+    readonly upstreamStatus: number | null;
+    readonly challenge: AuthChallenge | null;
+    constructor(code: McpErrorCode, status: 400 | 404 | 409 | 412 | 423 | 502, extra?: {
+        upstreamStatus?: number;
+        challenge?: AuthChallenge;
+    });
+}
+export declare function needsHandshake(err: unknown): boolean;

package/dist/public.d.ts

@@ -0,0 +1,4 @@
+export type { AdminServerItem, CallInput, CompleteOauthInput, ConnectResult, DescribedItem, HubResult, McpServerRow, OwnServerInput, SearchInput, ServerItem, ToolHit, ToolItem, Transient, } from "./rpc/types";
+export type { McpHubRpc } from "./rpc/hub-rpc";
+export type { McpAuth } from "./schema";
+export type { McpErrorCode } from "./errors";

package/dist/rpc/hub-rpc.d.ts

@@ -0,0 +1,28 @@
+import type { AdminServerInput, AdminServerItem, CallInput, CompleteOauthInput, ConnectResult, DescribedItem, HubResult, McpServerRow, OwnServerInput, SearchInput, ServerItem, ToolHit, ToolItem } from "./types";
+export interface McpHubRpc {
+    search(userId: string, input: SearchInput): Promise<HubResult<ToolHit[]>>;
+    describe(userId: string, tools: string[]): Promise<HubResult<{
+        items: DescribedItem[];
+    }>>;
+    call(userId: string, input: CallInput): Promise<HubResult<unknown>>;
+    listServers(userId: string): Promise<ServerItem[]>;
+    getServer(userId: string, serverId: string): Promise<McpServerRow | null>;
+    serverTools(userId: string, serverId: string): Promise<HubResult<{
+        items: ToolItem[];
+    }>>;
+    addServer(userId: string, input: OwnServerInput): Promise<McpServerRow>;
+    connectServer(userId: string, serverId: string, input: {
+        token?: string;
+    }): Promise<HubResult<ConnectResult>>;
+    completeOauth(userId: string, input: CompleteOauthInput): Promise<HubResult<{
+        server_id: string;
+    }>>;
+    refresh(userId: string, serverId: string): Promise<HubResult<{
+        tools: number;
+    }>>;
+    removeOwnServer(userId: string, serverId: string): Promise<void>;
+    disconnect(userId: string, serverId: string): Promise<void>;
+    adminServers(): Promise<AdminServerItem[]>;
+    upsertAdminServer(input: AdminServerInput): Promise<McpServerRow>;
+    clientMetadata(): Record<string, unknown>;
+}

package/dist/rpc/types.d.ts

@@ -0,0 +1,76 @@
+import type { CatalogServer, ToolHit } from "../catalog/types";
+import type { McpErrorCode } from "../errors";
+import type { McpAuth } from "../schema";
+export type { AdminServerInput, McpServerRow } from "../schema";
+export type { ToolHit };
+export type HubResult<T> = {
+    ok: true;
+    value: T;
+} | {
+    ok: false;
+    error: McpErrorCode;
+    status: 400 | 404 | 409 | 412 | 423 | 502;
+};
+export type Transient = {
+    user_id: string;
+    server_id: string;
+    state: string;
+    verifier: string;
+    issuer: string;
+    token_endpoint: string;
+    resource: string;
+    client_id: string;
+    exp: number;
+};
+export type SearchInput = {
+    q: string;
+    limit?: number;
+};
+export type CallInput = {
+    tool: string;
+    args?: unknown;
+    timeout_ms?: number;
+};
+export type DescribedItem = {
+    tool: string;
+    title: string | null;
+    description: string;
+    input_schema: unknown;
+    annotations: unknown;
+};
+export type ServerItem = {
+    id: string;
+    name: string;
+    url: string;
+    auth: McpAuth;
+    enabled: boolean;
+    own: boolean;
+    connected: boolean;
+    tool_count: number;
+    synced_at: number | null;
+};
+export type ToolItem = {
+    name: string;
+    title: string | null;
+    description: string;
+    annotations: unknown;
+};
+export type OwnServerInput = {
+    name: string;
+    url: string;
+    auth: McpAuth;
+};
+export type ConnectResult = {
+    connected: true;
+    tools: number;
+} | {
+    authorize_url: string;
+    transient: Transient;
+};
+export type CompleteOauthInput = {
+    transient: Transient;
+    code: string;
+    state: string | null;
+    iss: string | null;
+};
+export type AdminServerItem = CatalogServer;

package/dist/schema.d.ts

@@ -0,0 +1,32 @@
+export declare const AUTH_KINDS: readonly ["oauth", "bearer", "none"];
+export type McpAuth = (typeof AUTH_KINDS)[number];
+export type McpServerRow = {
+    id: string;
+    name: string;
+    url: string;
+    auth: McpAuth;
+    enabled: number;
+    owner: string | null;
+    updated_at: number;
+};
+export type McpToolRow = {
+    server_id: string;
+    name: string;
+    title: string | null;
+    description: string;
+    input_schema: string;
+    annotations: string | null;
+    owner: string | null;
+    updated_at: number;
+};
+export type AdminServerInput = {
+    id: string;
+    name: string;
+    url: string;
+    auth: McpAuth;
+    enabled?: boolean;
+};
+export declare function splitToolName(value: string): {
+    serverId: string;
+    name: string;
+} | null;

package/package.json

@@ -0,0 +1,49 @@
+{
+  "name": "@anyknown/mcp",
+  "version": "0.1.3",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/anyknown-com/mcp.git"
+  },
+  "files": [
+    "dist"
+  ],
+  "type": "module",
+  "exports": {
+    ".": {
+      "types": "./dist/public.d.ts"
+    }
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "scripts": {
+    "dev": "wrangler dev",
+    "typecheck": "wrangler types && tsc",
+    "test": "vitest run",
+    "migrate": "wrangler d1 migrations apply mcp --remote --env=\"\"",
+    "migrate:staging": "wrangler d1 migrations apply mcp-staging --remote --env staging",
+    "lint": "oxlint",
+    "lint:fix": "oxlint --fix",
+    "fmt": "oxfmt",
+    "fmt:check": "oxfmt --check",
+    "check": "pnpm typecheck && pnpm lint && pnpm fmt:check",
+    "types": "wrangler types",
+    "build:types": "tsc -p tsconfig.types.json"
+  },
+  "dependencies": {
+    "zod": "^4.5.4"
+  },
+  "devDependencies": {
+    "@cloudflare/vitest-pool-workers": "^0.22.0",
+    "@cloudflare/workers-types": "^5.20260830.1",
+    "@stylistic/eslint-plugin": "5.10.0",
+    "@types/node": "^26.4.0",
+    "oxfmt": "^0.65.0",
+    "oxlint": "^1.80.0",
+    "typescript": "^7.0.2",
+    "vitest": "^4.1.11",
+    "wrangler": "^4.127.1"
+  },
+  "packageManager": "pnpm@10.30.3"
+}