@ruco-ai/mcpster 0.2.5

package/README.md

@@ -0,0 +1,235 @@
+# mcpster
+
+> A TypeScript SDK for building MCP servers — removes the boilerplate so you focus on what you expose, not how.
+
+---
+
+## Overview
+
+mcpster is an agnostic TypeScript SDK for building Model Context Protocol (MCP) servers. It wraps `@modelcontextprotocol/sdk` behind a fluent, chainable API with Zod-first schema validation, URI template parsing, and consistent error handling. Servers built with mcpster start as local stdio processes and have a clear migration path to remote hosting and public npm distribution — without rewriting any business logic.
+
+## Features
+
+- `createServer()` + chainable `defineTool` / `defineResource` / `definePrompt` API
+- Zod schema validation enforced at tool registration time
+- URI template parameter extraction for resources (`templates://{name}`)
+- Automatic error wrapping — handlers throw, mcpster returns MCP-compliant error responses
+- Scope-aware server naming (project, user, or public scope)
+- stdio and Streamable HTTP transports — switch with a single config field
+- OAuth 2.1 (PKCE) support for protected remote servers — enable with `auth: true`
+- Designed for progressive deployment: local stdio → remote Streamable HTTP → hosted → npm package
+
+## Installation
+
+```bash
+npm install mcpster
+```
+
+## Usage
+
+### stdio (default)
+
+```typescript
+import { createServer } from 'mcpster'
+import { z } from 'zod'
+
+createServer({ name: 'my-server', version: '1.0.0' })
+  .defineTool({
+    name: 'get_template',
+    description: 'Retrieve a template by name',
+    schema: z.object({ name: z.string() }),
+    handler: async ({ name }) => { /* ... */ },
+  })
+  .defineResource({
+    uri: 'templates://{name}',
+    description: 'Template content by name',
+    resolver: async ({ name }) => { /* ... */ },
+  })
+  .definePrompt({
+    name: 'summarize',
+    handler: async (args) => { /* ... */ },
+  })
+  .start() // stdio transport
+```
+
+Register the server per-project:
+
+```bash
+claude mcp add my-server -- npx mcpster start
+```
+
+### Streamable HTTP transport
+
+```typescript
+import { createServer } from 'mcpster'
+
+createServer({
+  name: 'my-server',
+  version: '1.0.0',
+  transport: 'http',
+  http: { port: 3000, path: '/mcp' },
+})
+  .defineTool({ /* ... */ })
+  .start() // listens on http://localhost:3000/mcp
+```
+
+Register with Claude Code:
+
+```bash
+claude mcp add --transport http my-server http://localhost:3000/mcp
+```
+
+### OAuth 2.1 (protected remote server)
+
+Enable `auth: true` to require clients to complete an OAuth 2.1 PKCE flow before accessing the MCP endpoint. Set `baseUrl` to your public server URL so OAuth discovery metadata points to the right place.
+
+```typescript
+createServer({
+  name: 'my-server',
+  version: '1.0.0',
+  transport: 'http',
+  http: {
+    port: 3000,
+    path: '/mcp',
+    auth: true,
+    baseUrl: 'https://my-server.example.com',
+  },
+}).start()
+```
+
+mcpster handles the full OAuth flow: dynamic client registration (`/register`), authorization (`/authorize`), token issuance (`/token`), and bearer token verification on the MCP endpoint. All dynamically registered clients are treated as public PKCE clients — no pre-shared secrets required.
+
+For persistence across restarts, point `clientsFile` at a file on a mounted volume:
+
+```typescript
+http: {
+  auth: true,
+  baseUrl: 'https://my-server.example.com',
+  clientsFile: '/data/oauth-clients.json',
+}
+```
+
+## Configuration
+
+| Option | Default | Description |
+|--------|---------|-------------|
+| `name` | required | Server name, used for MCP registration |
+| `version` | required | Semver string |
+| `scope` | `process.cwd()` | Project root; determines scope for naming and resource resolution |
+| `transport` | `'stdio'` | Transport to use: `'stdio'` or `'http'` |
+| `http.port` | `3000` | Port to listen on (HTTP transport only) |
+| `http.path` | `'/mcp'` | Request path to handle (HTTP transport only) |
+| `http.auth` | `false` | Enable OAuth 2.1 PKCE protection on the MCP endpoint |
+| `http.baseUrl` | `http://localhost:<port>` | Public base URL — used for OAuth metadata and token endpoints |
+| `http.clientsFile` | *(in-memory)* | Path to persist registered OAuth clients across restarts |
+
+## Project Structure
+
+```
+mcpster/
+├── src/
+│   ├── index.ts              # Public API — re-exports createServer and types
+│   ├── server.ts             # McpsterServer class — core orchestrator
+│   ├── tool.ts               # defineTool — schema validation + handler wiring
+│   ├── resource.ts           # defineResource — URI template matching + resolver
+│   ├── prompt.ts             # definePrompt — prompt template registration
+│   ├── transport/
+│   │   ├── stdio.ts          # stdio transport adapter
+│   │   └── http.ts           # Streamable HTTP transport adapter
+│   ├── deploy/
+│   │   ├── types.ts          # Shared DeployConfig, DeployResult, DeployAdapter types
+│   │   ├── railway.ts        # Railway adapter (generateManifest, deploy)
+│   │   ├── fly.ts            # Fly.io adapter (generateManifest, generateDockerfile, deploy)
+│   │   ├── cloudflare.ts     # Cloudflare Workers adapter (generateManifest, generateWorkerShim, deploy)
+│   │   └── cli.ts            # mcpster-deploy CLI entry point
+│   └── types.ts              # Shared TypeScript types and interfaces
+├── tests/
+│   ├── server.test.ts
+│   ├── tool.test.ts
+│   ├── resource.test.ts
+│   ├── prompt.test.ts
+│   ├── transport.test.ts
+│   └── deploy.test.ts
+├── examples/
+│   └── minimal/              # hello-mcp — tool + resource + prompt, runnable reference
+├── package.json
+└── tsconfig.json
+```
+
+## Deploy (v3)
+
+mcpster ships a deploy kit that pushes your Streamable HTTP server to Railway, Fly.io, or Cloudflare Workers with a single command. The Streamable HTTP transport must already be configured on your server before deploying — the deploy adapters wrap the existing `transport: 'http'` path.
+
+### Prerequisites
+
+| Target | Prerequisite |
+|--------|-------------|
+| Railway | `railway` CLI installed and authenticated (`railway login`) |
+| Fly.io | `flyctl` installed and authenticated (`fly auth login`) |
+| Cloudflare Workers | `wrangler` installed and authenticated (`wrangler login`) |
+
+### Usage
+
+```bash
+# Dry-run: print the generated manifest without deploying
+npx mcpster-deploy --target railway --dry-run
+npx mcpster-deploy --target fly --dry-run
+npx mcpster-deploy --target cloudflare --dry-run
+
+# Deploy
+npx mcpster-deploy --target railway
+npx mcpster-deploy --target fly --region lhr
+npx mcpster-deploy --target cloudflare
+```
+
+All options:
+
+```
+-t, --target <target>    Deploy target (railway | fly | cloudflare)
+-n, --name <name>        Server name (default: read from package.json)
+-v, --version <version>  Server version (default: read from package.json)
+-p, --port <port>        HTTP port (default: 3000)
+-r, --region <region>    Preferred region — Fly.io only (default: iad)
+-d, --dry-run            Print the generated manifest without deploying
+-h, --help               Show help
+```
+
+### Local → Hosted migration path
+
+**Stage 1 — Local stdio** (no infrastructure)
+
+```typescript
+createServer({ name: 'my-server', version: '1.0.0' }).start()
+```
+
+**Stage 2 — Local Streamable HTTP** (same server, different transport)
+
+```typescript
+createServer({
+  name: 'my-server',
+  version: '1.0.0',
+  transport: 'http',
+  http: { port: 3000, path: '/mcp' },
+}).start()
+```
+
+**Stage 3 — Hosted** (one command, no code changes)
+
+```bash
+npx mcpster-deploy --target railway
+# → Deployed to Railway: https://my-server.up.railway.app
+```
+
+Then connect Claude Code to the deployed server:
+
+```bash
+claude mcp add --transport http my-server https://my-server.up.railway.app/mcp
+```
+
+The server code is identical across all three stages.
+
+## License
+
+MIT
+
+---

package/dist/deploy/cli.d.ts

@@ -0,0 +1,8 @@
+#!/usr/bin/env node
+/**
+ * mcpster deploy CLI
+ *
+ * Usage:
+ *   mcpster-deploy --target <railway|fly|cloudflare> [--name <name>] [--version <v>] [--port <port>] [--dry-run]
+ */
+export {};

package/dist/deploy/cli.js

@@ -0,0 +1,106 @@
+#!/usr/bin/env node
+/**
+ * mcpster deploy CLI
+ *
+ * Usage:
+ *   mcpster-deploy --target <railway|fly|cloudflare> [--name <name>] [--version <v>] [--port <port>] [--dry-run]
+ */
+import { parseArgs } from 'node:util';
+const { values } = parseArgs({
+    options: {
+        target: { type: 'string', short: 't' },
+        name: { type: 'string', short: 'n' },
+        version: { type: 'string', short: 'v' },
+        port: { type: 'string', short: 'p' },
+        region: { type: 'string', short: 'r' },
+        'dry-run': { type: 'boolean', short: 'd' },
+        help: { type: 'boolean', short: 'h' },
+    },
+    allowPositionals: false,
+});
+if (values.help || !values.target) {
+    console.log(`
+mcpster deploy — push your MCP server to a hosted platform
+
+Usage:
+  mcpster-deploy --target <target> [options]
+
+Targets:
+  railway      Deploy to Railway (requires: railway CLI)
+  fly          Deploy to Fly.io  (requires: flyctl)
+  cloudflare   Deploy to Cloudflare Workers (requires: wrangler)
+
+Options:
+  -t, --target <target>    Deploy target (railway | fly | cloudflare)
+  -n, --name <name>        Server name (default: read from package.json)
+  -v, --version <version>  Server version (default: read from package.json)
+  -p, --port <port>        HTTP port (default: 3000)
+  -r, --region <region>    Preferred region (fly only, default: iad)
+  -d, --dry-run            Print the generated manifest without deploying
+  -h, --help               Show this help message
+`);
+    process.exit(values.help ? 0 : 1);
+}
+const target = values.target;
+if (!['railway', 'fly', 'cloudflare'].includes(target)) {
+    console.error(`Error: unknown target "${target}". Must be one of: railway, fly, cloudflare`);
+    process.exit(1);
+}
+// Resolve name and version from package.json if not provided
+async function resolvePackageMeta() {
+    try {
+        const { readFileSync } = await import('node:fs');
+        const pkg = JSON.parse(readFileSync('package.json', 'utf8'));
+        return {
+            name: pkg.name ?? 'mcp-server',
+            version: pkg.version ?? '0.1.0',
+        };
+    }
+    catch {
+        return { name: 'mcp-server', version: '0.1.0' };
+    }
+}
+const meta = await resolvePackageMeta();
+const config = {
+    name: values.name ?? meta.name,
+    version: values.version ?? meta.version,
+    port: values.port ? Number(values.port) : 3000,
+    region: values.region,
+};
+const dryRun = values['dry-run'] ?? false;
+if (target === 'railway') {
+    const { generateManifest, deploy } = await import('./railway.js');
+    if (dryRun) {
+        console.log(JSON.stringify(generateManifest(config), null, 2));
+    }
+    else {
+        const result = await deploy(config);
+        console.log(`Deployed to Railway: ${result.url}`);
+    }
+}
+else if (target === 'fly') {
+    const { generateManifest, generateDockerfile, deploy } = await import('./fly.js');
+    if (dryRun) {
+        console.log('# fly.toml');
+        console.log(JSON.stringify(generateManifest(config), null, 2));
+        console.log('\n# Dockerfile');
+        console.log(generateDockerfile());
+    }
+    else {
+        const result = await deploy(config);
+        console.log(`Deployed to Fly.io: ${result.url}`);
+    }
+}
+else if (target === 'cloudflare') {
+    const { generateManifest, manifestToToml, generateWorkerShim, deploy } = await import('./cloudflare.js');
+    if (dryRun) {
+        console.log('# wrangler.toml');
+        console.log(manifestToToml(generateManifest(config)));
+        console.log('\n# worker.js');
+        console.log(generateWorkerShim(config));
+    }
+    else {
+        const result = await deploy(config);
+        console.log(`Deployed to Cloudflare Workers: ${result.url}`);
+    }
+}

package/dist/deploy/cloudflare.d.ts

@@ -0,0 +1,11 @@
+import type { DeployConfig, DeployResult } from './types.js';
+export interface CloudflareManifest {
+    name: string;
+    main: string;
+    compatibility_date: string;
+    vars: Record<string, string>;
+}
+export declare function generateManifest(config: DeployConfig): CloudflareManifest;
+export declare function generateWorkerShim(config: DeployConfig): string;
+export declare function manifestToToml(manifest: CloudflareManifest): string;
+export declare function deploy(config: DeployConfig): Promise<DeployResult>;

package/dist/deploy/cloudflare.js

@@ -0,0 +1,57 @@
+import { execSync } from 'node:child_process';
+export function generateManifest(config) {
+    return {
+        name: config.name,
+        main: 'worker.js',
+        compatibility_date: '2024-01-01',
+        vars: {
+            MCP_TRANSPORT: 'http',
+            SERVER_NAME: config.name,
+            SERVER_VERSION: config.version,
+        },
+    };
+}
+export function generateWorkerShim(config) {
+    const port = config.port ?? 3000;
+    return [
+        `// Worker entry shim for ${config.name} v${config.version}`,
+        `// Forwards requests to the MCP HTTP handler`,
+        `import { createServer } from './dist/index.js'`,
+        ``,
+        `const server = createServer({`,
+        `  name: '${config.name}',`,
+        `  version: '${config.version}',`,
+        `  transport: 'http',`,
+        `  http: { port: ${port}, path: '/mcp' },`,
+        `})`,
+        ``,
+        `export default {`,
+        `  async fetch(request, env, ctx) {`,
+        `    return server.handleRequest(request, env, ctx)`,
+        `  },`,
+        `}`,
+    ].join('\n');
+}
+export function manifestToToml(manifest) {
+    const lines = [
+        `name = "${manifest.name}"`,
+        `main = "${manifest.main}"`,
+        `compatibility_date = "${manifest.compatibility_date}"`,
+        ``,
+        `[vars]`,
+    ];
+    for (const [key, value] of Object.entries(manifest.vars)) {
+        lines.push(`${key} = "${value}"`);
+    }
+    return lines.join('\n');
+}
+export async function deploy(config) {
+    const manifest = generateManifest(config);
+    const { writeFileSync } = await import('node:fs');
+    writeFileSync('wrangler.toml', manifestToToml(manifest), 'utf8');
+    writeFileSync('worker.js', generateWorkerShim(config), 'utf8');
+    const output = execSync('wrangler deploy --json', { encoding: 'utf8' });
+    const result = JSON.parse(output);
+    const url = result.url ?? result.deployment_url ?? `https://${config.name}.workers.dev`;
+    return { url, target: 'cloudflare', manifest };
+}

package/dist/deploy/fly.d.ts

@@ -0,0 +1,12 @@
+import type { DeployConfig, DeployResult } from './types.js';
+export interface FlyManifest {
+    app: string;
+    primary_region: string;
+    [services: string]: unknown;
+}
+export interface FlyDockerfile {
+    content: string;
+}
+export declare function generateManifest(config: DeployConfig): FlyManifest;
+export declare function generateDockerfile(): string;
+export declare function deploy(config: DeployConfig): Promise<DeployResult>;

package/dist/deploy/fly.js

@@ -0,0 +1,86 @@
+import { execSync } from 'node:child_process';
+import { readdirSync } from 'node:fs';
+export function generateManifest(config) {
+    const port = config.port ?? 3000;
+    return {
+        app: config.name,
+        primary_region: config.region ?? 'iad',
+        build: { dockerfile: 'Dockerfile' },
+        http_service: {
+            internal_port: port,
+            force_https: true,
+            auto_stop_machines: true,
+            auto_start_machines: true,
+        },
+        vm: [
+            {
+                memory: config.memory ?? '256mb',
+                cpu_kind: 'shared',
+                cpus: 1,
+            },
+        ],
+        env: {
+            PORT: String(port),
+            MCP_TRANSPORT: 'http',
+            SERVER_NAME: config.name,
+            SERVER_VERSION: config.version,
+        },
+    };
+}
+export function generateDockerfile() {
+    let tgzFiles = [];
+    try {
+        tgzFiles = readdirSync('.').filter((f) => f.endsWith('.tgz'));
+    }
+    catch {
+        // ignore
+    }
+    const lines = [
+        'FROM node:20-alpine',
+        'WORKDIR /app',
+        'COPY package*.json ./',
+        ...(tgzFiles.length > 0 ? [`COPY ${tgzFiles.join(' ')} ./`] : []),
+        'RUN npm ci --omit=dev',
+        'COPY dist ./dist',
+        'COPY mcpster.config.json ./',
+        'EXPOSE 3000',
+        'CMD ["node", "dist/index.js"]',
+    ];
+    return lines.join('\n');
+}
+export async function deploy(config) {
+    const manifest = generateManifest(config);
+    const { writeFileSync } = await import('node:fs');
+    writeFileSync('fly.toml', toToml(manifest), 'utf8');
+    writeFileSync('Dockerfile', generateDockerfile(), 'utf8');
+    execSync('fly deploy', { encoding: 'utf8', stdio: 'inherit' });
+    const infoOutput = execSync(`fly status --app ${config.name} --json`, { encoding: 'utf8' });
+    const info = JSON.parse(infoOutput);
+    const url = info.Hostname ? `https://${info.Hostname}` : '';
+    return { url, target: 'fly', manifest };
+}
+function toToml(obj, indent = 0) {
+    const lines = [];
+    const pad = ' '.repeat(indent);
+    for (const [key, value] of Object.entries(obj)) {
+        if (value === null || value === undefined)
+            continue;
+        if (Array.isArray(value)) {
+            for (const item of value) {
+                lines.push(`${pad}[[${key}]]`);
+                lines.push(toToml(item, indent + 2));
+            }
+        }
+        else if (typeof value === 'object') {
+            lines.push(`${pad}[${key}]`);
+            lines.push(toToml(value, indent + 2));
+        }
+        else if (typeof value === 'string') {
+            lines.push(`${pad}${key} = "${value}"`);
+        }
+        else {
+            lines.push(`${pad}${key} = ${String(value)}`);
+        }
+    }
+    return lines.join('\n');
+}

package/dist/deploy/railway.d.ts

@@ -0,0 +1,19 @@
+import type { DeployConfig, DeployResult } from './types.js';
+export interface RailwayManifest {
+    '$schema': string;
+    build: {
+        builder: string;
+    };
+    deploy: {
+        startCommand: string;
+        healthcheckPath: string;
+        restartPolicyType: string;
+    };
+    environments: {
+        production: {
+            variables: Record<string, string>;
+        };
+    };
+}
+export declare function generateManifest(config: DeployConfig): RailwayManifest;
+export declare function deploy(config: DeployConfig): Promise<DeployResult>;

package/dist/deploy/railway.js

@@ -0,0 +1,34 @@
+import { execSync } from 'node:child_process';
+export function generateManifest(config) {
+    const port = config.port ?? 3000;
+    return {
+        '$schema': 'https://railway.app/railway.schema.json',
+        build: { builder: 'NIXPACKS' },
+        deploy: {
+            startCommand: `node dist/index.js`,
+            healthcheckPath: '/mcp',
+            restartPolicyType: 'ON_FAILURE',
+        },
+        environments: {
+            production: {
+                variables: {
+                    PORT: String(port),
+                    MCP_TRANSPORT: 'http',
+                    SERVER_NAME: config.name,
+                    SERVER_VERSION: config.version,
+                },
+            },
+        },
+    };
+}
+export async function deploy(config) {
+    const manifest = generateManifest(config);
+    const json = JSON.stringify(manifest, null, 2);
+    // Write railway.json then invoke CLI
+    const { writeFileSync } = await import('node:fs');
+    writeFileSync('railway.json', json, 'utf8');
+    const output = execSync('railway up --json', { encoding: 'utf8' });
+    const result = JSON.parse(output);
+    const url = result.url ?? result.deploymentUrl ?? '';
+    return { url, target: 'railway', manifest };
+}

package/dist/deploy/types.d.ts

@@ -0,0 +1,18 @@
+export type DeployTarget = 'railway' | 'fly' | 'cloudflare';
+export interface DeployConfig {
+    name: string;
+    version: string;
+    port?: number;
+    region?: string;
+    memory?: string;
+    cpu?: string;
+}
+export interface DeployResult {
+    url: string;
+    target: DeployTarget;
+    manifest: unknown;
+}
+export interface DeployAdapter {
+    generateManifest(config: DeployConfig): unknown;
+    deploy(config: DeployConfig): Promise<DeployResult>;
+}

package/dist/deploy/types.js

@@ -0,0 +1 @@
+export {};

package/dist/index.d.ts

@@ -0,0 +1,2 @@
+export { createServer } from './server.js';
+export type { McpsterServer, ServerConfig, HttpConfig, ToolDefinition, ResourceDefinition, PromptDefinition, SetupOptions, PermissionMode } from './types.js';

package/dist/index.js

@@ -0,0 +1 @@
+export { createServer } from './server.js';

package/dist/prompt.d.ts

@@ -0,0 +1,3 @@
+import type { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
+import type { PromptDefinition } from './types.js';
+export declare function registerPrompt(sdk: McpServer, def: PromptDefinition): void;

package/dist/prompt.js

@@ -0,0 +1,16 @@
+export function registerPrompt(sdk, def) {
+    sdk.registerPrompt(def.name, { description: def.description }, async (args) => {
+        try {
+            const text = await def.handler(args);
+            return {
+                messages: [{ role: 'user', content: { type: 'text', text } }],
+            };
+        }
+        catch (err) {
+            const message = err instanceof Error ? err.message : String(err);
+            return {
+                messages: [{ role: 'user', content: { type: 'text', text: message } }],
+            };
+        }
+    });
+}

package/dist/resource.d.ts

@@ -0,0 +1,3 @@
+import { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
+import type { ResourceDefinition } from './types.js';
+export declare function registerResource(sdk: McpServer, def: ResourceDefinition): void;

package/dist/resource.js

@@ -0,0 +1,36 @@
+import { ResourceTemplate } from '@modelcontextprotocol/sdk/server/mcp.js';
+function parseUriParams(uri) {
+    return [...uri.matchAll(/\{(\w+)\}/g)].map(m => m[1]);
+}
+export function registerResource(sdk, def) {
+    const params = parseUriParams(def.uri);
+    if (params.length === 0) {
+        sdk.registerResource(def.uri, def.uri, { description: def.description }, async () => {
+            try {
+                const text = await def.resolver({});
+                return { contents: [{ uri: def.uri, text }] };
+            }
+            catch (err) {
+                const message = err instanceof Error ? err.message : String(err);
+                return { contents: [{ uri: def.uri, text: message }] };
+            }
+        });
+    }
+    else {
+        const template = new ResourceTemplate(def.uri, { list: undefined });
+        sdk.registerResource(def.uri, template, { description: def.description }, async (uri, variables) => {
+            try {
+                const extracted = {};
+                for (const [k, v] of Object.entries(variables)) {
+                    extracted[k] = Array.isArray(v) ? v[0] : String(v);
+                }
+                const text = await def.resolver(extracted);
+                return { contents: [{ uri: uri.toString(), text }] };
+            }
+            catch (err) {
+                const message = err instanceof Error ? err.message : String(err);
+                return { contents: [{ uri: uri.toString(), text: message }] };
+            }
+        });
+    }
+}

package/dist/server.d.ts

@@ -0,0 +1,2 @@
+import type { ServerConfig, McpsterServer } from './types.js';
+export declare function createServer(config: ServerConfig): McpsterServer;

package/dist/server.js

@@ -0,0 +1,51 @@
+import { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
+import { connectStdio } from './transport/stdio.js';
+import { connectHttp } from './transport/http.js';
+import { registerTool } from './tool.js';
+import { registerResource } from './resource.js';
+import { registerPrompt } from './prompt.js';
+import { applySetup } from './setup.js';
+class McpsterServerImpl {
+    sdk;
+    config;
+    toolNames = [];
+    _stop;
+    constructor(config) {
+        this.config = config;
+        this.sdk = new McpServer({
+            name: config.name,
+            version: config.version,
+        });
+    }
+    defineTool(def) {
+        registerTool(this.sdk, def);
+        this.toolNames.push(def.name);
+        return this;
+    }
+    defineResource(def) {
+        registerResource(this.sdk, def);
+        return this;
+    }
+    definePrompt(def) {
+        registerPrompt(this.sdk, def);
+        return this;
+    }
+    async setup(options) {
+        applySetup(this.config.name, this.toolNames, options);
+        return this;
+    }
+    async start() {
+        if (this.config.transport === 'http') {
+            this._stop = await connectHttp(this.sdk, this.config.http);
+        }
+        else {
+            this._stop = await connectStdio(this.sdk);
+        }
+    }
+    async stop() {
+        await this._stop?.();
+    }
+}
+export function createServer(config) {
+    return new McpsterServerImpl(config);
+}

package/dist/setup.d.ts

@@ -0,0 +1,2 @@
+import type { SetupOptions } from './types.js';
+export declare function applySetup(serverName: string, toolNames: string[], options?: SetupOptions): void;

package/dist/setup.js

@@ -0,0 +1,34 @@
+import { readFileSync, writeFileSync } from 'fs';
+import { homedir } from 'os';
+import { resolve } from 'path';
+function claudeJsonPath() {
+    return resolve(homedir(), '.claude.json');
+}
+function readClaudeJson() {
+    try {
+        return JSON.parse(readFileSync(claudeJsonPath(), 'utf8'));
+    }
+    catch {
+        return {};
+    }
+}
+function writeClaudeJson(data) {
+    writeFileSync(claudeJsonPath(), JSON.stringify(data, null, 2) + '\n', 'utf8');
+}
+export function applySetup(serverName, toolNames, options = {}) {
+    const projectPath = resolve(options.projectPath ?? process.cwd());
+    const permissions = options.permissions ?? 'restrictive';
+    const claude = readClaudeJson();
+    const projects = (claude.projects ?? {});
+    const project = projects[projectPath] ?? {};
+    const allowedTools = permissions === 'permissive'
+        ? toolNames.map(name => `${serverName}:${name}`)
+        : [];
+    projects[projectPath] = { ...project, allowedTools };
+    claude.projects = projects;
+    writeClaudeJson(claude);
+    console.error(`[mcpster] setup complete — permissions: ${permissions}`);
+    if (allowedTools.length > 0) {
+        console.error(`[mcpster] allowed tools: ${allowedTools.join(', ')}`);
+    }
+}

package/dist/tool.d.ts

@@ -0,0 +1,4 @@
+import type { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
+import { ZodSchema } from 'zod';
+import type { ToolDefinition } from './types.js';
+export declare function registerTool<T extends ZodSchema>(sdk: McpServer, def: ToolDefinition<T>): void;

package/dist/tool.js

@@ -0,0 +1,17 @@
+export function registerTool(sdk, def) {
+    const shape = def.schema.shape;
+    sdk.registerTool(def.name, {
+        description: def.description,
+        inputSchema: shape,
+    }, async (args) => {
+        try {
+            const result = await def.handler(args);
+            const text = typeof result === 'string' ? result : JSON.stringify(result);
+            return { content: [{ type: 'text', text }] };
+        }
+        catch (err) {
+            const message = err instanceof Error ? err.message : String(err);
+            return { content: [{ type: 'text', text: message }], isError: true };
+        }
+    });
+}

package/dist/transport/http.d.ts

@@ -0,0 +1,3 @@
+import type { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
+import type { HttpConfig } from '../types.js';
+export declare function connectHttp(server: McpServer, config?: HttpConfig): Promise<() => Promise<void>>;

package/dist/transport/http.js

@@ -0,0 +1,228 @@
+import express from 'express';
+import { randomUUID } from 'node:crypto';
+import { readFileSync, writeFileSync, mkdirSync } from 'node:fs';
+import { dirname } from 'node:path';
+import { StreamableHTTPServerTransport } from '@modelcontextprotocol/sdk/server/streamableHttp.js';
+import { mcpAuthRouter } from '@modelcontextprotocol/sdk/server/auth/router.js';
+import { requireBearerAuth } from '@modelcontextprotocol/sdk/server/auth/middleware/bearerAuth.js';
+function createClientsStore(clientsFile) {
+    const clients = new Map();
+    if (clientsFile) {
+        try {
+            const raw = readFileSync(clientsFile, 'utf8');
+            const stored = JSON.parse(raw);
+            for (const c of stored)
+                clients.set(c.client_id, c);
+        }
+        catch {
+            // File doesn't exist yet — start empty
+        }
+    }
+    function persist() {
+        if (!clientsFile)
+            return;
+        try {
+            mkdirSync(dirname(clientsFile), { recursive: true });
+            writeFileSync(clientsFile, JSON.stringify([...clients.values()], null, 2), 'utf8');
+        }
+        catch (err) {
+            console.error('[mcpster] Failed to persist OAuth clients:', err);
+        }
+    }
+    return {
+        getClient: (id) => clients.get(id) ?? undefined,
+        registerClient: (client) => {
+            // Always treat dynamically registered clients as public (no client_secret).
+            // This allows clients like Claude.ai that use PKCE and never send a secret
+            // to complete the token exchange, regardless of what they sent at registration.
+            const { client_secret: _secret, client_secret_expires_at: _exp, ...rest } = client;
+            const full = {
+                redirect_uris: [],
+                ...rest,
+                token_endpoint_auth_method: 'none',
+                client_id: randomUUID(),
+                client_id_issued_at: Math.floor(Date.now() / 1000),
+            };
+            clients.set(full.client_id, full);
+            persist();
+            return full;
+        },
+    };
+}
+// ---------------------------------------------------------------------------
+// OAuth 2.1 provider (PKCE, dynamic client registration)
+// ---------------------------------------------------------------------------
+function createOAuthProvider(clientsFile) {
+    const clientsStore = createClientsStore(clientsFile);
+    const authCodes = new Map();
+    const tokens = new Map();
+    const refreshTokens = new Map();
+    const esc = (s) => String(s ?? '').replace(/&/g, '&amp;').replace(/"/g, '&quot;').replace(/</g, '&lt;');
+    return {
+        get clientsStore() { return clientsStore; },
+        async authorize(client, params, res) {
+            const code = randomUUID();
+            authCodes.set(code, {
+                clientId: client.client_id,
+                codeChallenge: params.codeChallenge,
+                redirectUri: params.redirectUri,
+                scopes: params.scopes ?? [],
+            });
+            res.send(`<!DOCTYPE html>
+<html lang="en">
+<head>
+  <meta charset="utf-8">
+  <title>Authorize — ${esc(client.client_name ?? client.client_id)}</title>
+  <style>
+    body { font-family: system-ui, sans-serif; max-width: 480px; margin: 80px auto; padding: 0 20px; }
+    h2  { margin-bottom: 8px; }
+    p   { color: #555; margin-bottom: 24px; }
+    button { padding: 10px 20px; border-radius: 6px; font-size: 15px; cursor: pointer; border: 1px solid #ccc; }
+    .approve { background: #0070f3; color: #fff; border-color: #0070f3; margin-right: 10px; }
+  </style>
+</head>
+<body>
+  <h2>Authorization Request</h2>
+  <p><strong>${esc(client.client_name ?? client.client_id)}</strong> is requesting access to this MCP server.</p>
+  <form method="POST" action="/approve">
+    <input type="hidden" name="code"         value="${esc(code)}">
+    <input type="hidden" name="redirect_uri" value="${esc(params.redirectUri)}">
+    <input type="hidden" name="state"        value="${esc(params.state ?? '')}">
+    <button class="approve" type="submit">Approve</button>
+    <button type="button" onclick="history.back()">Deny</button>
+  </form>
+</body>
+</html>`);
+        },
+        async challengeForAuthorizationCode(client, code) {
+            const entry = authCodes.get(code);
+            if (!entry || entry.clientId !== client.client_id)
+                throw new Error('Invalid authorization code');
+            return entry.codeChallenge;
+        },
+        async exchangeAuthorizationCode(client, code) {
+            const entry = authCodes.get(code);
+            if (!entry || entry.clientId !== client.client_id)
+                throw new Error('Invalid authorization code');
+            authCodes.delete(code);
+            const accessToken = randomUUID();
+            const refreshToken = randomUUID();
+            const expiresAt = Math.floor(Date.now() / 1000) + 3600;
+            tokens.set(accessToken, { token: accessToken, clientId: client.client_id, scopes: entry.scopes, expiresAt, refreshToken });
+            refreshTokens.set(refreshToken, accessToken);
+            return { access_token: accessToken, token_type: 'bearer', expires_in: 3600, refresh_token: refreshToken };
+        },
+        async exchangeRefreshToken(client, oldRefreshToken) {
+            const oldAccess = refreshTokens.get(oldRefreshToken);
+            if (!oldAccess)
+                throw new Error('Invalid refresh token');
+            const old = tokens.get(oldAccess);
+            if (!old)
+                throw new Error('Invalid refresh token');
+            const accessToken = randomUUID();
+            const newRefresh = randomUUID();
+            const expiresAt = Math.floor(Date.now() / 1000) + 3600;
+            tokens.delete(oldAccess);
+            refreshTokens.delete(oldRefreshToken);
+            tokens.set(accessToken, { token: accessToken, clientId: client.client_id, scopes: old.scopes, expiresAt, refreshToken: newRefresh });
+            refreshTokens.set(newRefresh, accessToken);
+            return { access_token: accessToken, token_type: 'bearer', expires_in: 3600, refresh_token: newRefresh };
+        },
+        async verifyAccessToken(token) {
+            const info = tokens.get(token);
+            if (!info)
+                throw new Error('Invalid token');
+            if (info.expiresAt < Math.floor(Date.now() / 1000))
+                throw new Error('Token expired');
+            return info;
+        },
+    };
+}
+// ---------------------------------------------------------------------------
+// HTTP transport with OAuth 2.1
+// ---------------------------------------------------------------------------
+export async function connectHttp(server, config) {
+    const port = config?.port ?? 3000;
+    const path = config?.path ?? '/mcp';
+    // baseUrl drives OAuth metadata (issuer, token endpoint, etc.).
+    // Priority: config.baseUrl → BASE_URL env → http://localhost:<port>
+    const envBaseUrl = process.env.BASE_URL;
+    const rawBaseUrl = config?.baseUrl || (envBaseUrl?.startsWith('http') ? envBaseUrl : undefined) || `http://localhost:${port}`;
+    const baseUrl = new URL(rawBaseUrl);
+    const authEnabled = config?.auth ?? false;
+    const app = express();
+    // Behind a reverse proxy (Fly.io, Railway, etc.) there is exactly one hop.
+    app.set('trust proxy', 1);
+    app.use(express.json());
+    app.use(express.urlencoded({ extended: false }));
+    // Request logging
+    app.use((req, _res, next) => {
+        console.log(`[mcpster] ${req.method} ${req.path}`, req.body && Object.keys(req.body).length ? JSON.stringify(req.body) : '');
+        next();
+    });
+    if (authEnabled) {
+        if (!config?.clientsFile && !process.env.MCPSTER_CLIENTS_FILE) {
+            console.warn('[mcpster] Warning: running HTTP transport without clientsFile — registered OAuth clients ' +
+                'are stored in memory only and will be lost on restart. Set http.clientsFile in ' +
+                'mcpster.config.json (e.g. "/data/oauth-clients.json") and mount a persistent volume.');
+        }
+        const provider = createOAuthProvider(config?.clientsFile ?? process.env.MCPSTER_CLIENTS_FILE);
+        // OAuth discovery + registration + token endpoints
+        app.use(mcpAuthRouter({ provider, issuerUrl: baseUrl }));
+        // Approve endpoint — browser page shown during the OAuth flow
+        app.post('/approve', (req, res) => {
+            const { code, redirect_uri, state } = req.body;
+            if (!code || !redirect_uri) {
+                res.status(400).send('Missing code or redirect_uri');
+                return;
+            }
+            const url = new URL(redirect_uri);
+            url.searchParams.set('code', code);
+            if (state)
+                url.searchParams.set('state', state);
+            res.redirect(url.toString());
+        });
+        // MCP endpoint — protected by bearer token
+        // resourceMetadataUrl tells clients where to find OAuth discovery metadata (RFC 9728)
+        const resourceMetadataUrl = new URL('/.well-known/oauth-protected-resource', baseUrl).href;
+        app.all(path, requireBearerAuth({ verifier: provider, resourceMetadataUrl }), async (req, res) => {
+            const transport = new StreamableHTTPServerTransport({ sessionIdGenerator: undefined, enableJsonResponse: config?.enableJsonResponse });
+            try {
+                await server.connect(transport);
+                await transport.handleRequest(req, res, req.body);
+            }
+            catch {
+                if (!res.headersSent)
+                    res.status(500).end();
+            }
+            finally {
+                await transport.close();
+            }
+        });
+    }
+    else {
+        // No auth — MCP endpoint is open
+        app.all(path, async (req, res) => {
+            const transport = new StreamableHTTPServerTransport({ sessionIdGenerator: undefined, enableJsonResponse: config?.enableJsonResponse });
+            try {
+                await server.connect(transport);
+                await transport.handleRequest(req, res, req.body);
+            }
+            catch {
+                if (!res.headersSent)
+                    res.status(500).end();
+            }
+            finally {
+                await transport.close();
+            }
+        });
+    }
+    const httpServer = app.listen(port);
+    await new Promise((resolve, reject) => {
+        httpServer.once('listening', resolve);
+        httpServer.once('error', reject);
+    });
+    return () => new Promise((resolve, reject) => {
+        httpServer.close((err) => (err ? reject(err) : resolve()));
+    });
+}

package/dist/transport/stdio.d.ts

@@ -0,0 +1,2 @@
+import type { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
+export declare function connectStdio(server: McpServer): Promise<() => Promise<void>>;

package/dist/transport/stdio.js

@@ -0,0 +1,6 @@
+import { StdioServerTransport } from '@modelcontextprotocol/sdk/server/stdio.js';
+export async function connectStdio(server) {
+    const transport = new StdioServerTransport();
+    await server.connect(transport);
+    return () => Promise.resolve();
+}

package/dist/types.d.ts

@@ -0,0 +1,45 @@
+import type { z, ZodSchema } from 'zod';
+export interface HttpConfig {
+    port?: number;
+    path?: string;
+    baseUrl?: string;
+    auth?: boolean;
+    clientsFile?: string;
+    enableJsonResponse?: boolean;
+}
+export interface ServerConfig {
+    name: string;
+    version: string;
+    scope?: string;
+    transport?: 'stdio' | 'http';
+    http?: HttpConfig;
+}
+export interface ToolDefinition<T extends ZodSchema = ZodSchema> {
+    name: string;
+    description: string;
+    schema: T;
+    handler: (input: z.infer<T>) => Promise<unknown>;
+}
+export interface ResourceDefinition {
+    uri: string;
+    description: string;
+    resolver: (params: Record<string, string>) => Promise<string>;
+}
+export interface PromptDefinition {
+    name: string;
+    description?: string;
+    handler: (args: Record<string, string>) => Promise<string>;
+}
+export type PermissionMode = 'permissive' | 'restrictive';
+export interface SetupOptions {
+    permissions?: PermissionMode;
+    projectPath?: string;
+}
+export interface McpsterServer {
+    defineTool<T extends ZodSchema>(def: ToolDefinition<T>): McpsterServer;
+    defineResource(def: ResourceDefinition): McpsterServer;
+    definePrompt(def: PromptDefinition): McpsterServer;
+    setup(options?: SetupOptions): Promise<McpsterServer>;
+    start(): Promise<void>;
+    stop(): Promise<void>;
+}

package/dist/types.js

@@ -0,0 +1 @@
+export {};

package/package.json

@@ -0,0 +1,52 @@
+{
+  "name": "@ruco-ai/mcpster",
+  "version": "0.2.5",
+  "description": "Agnostic TypeScript SDK for building MCP servers",
+  "license": "MIT",
+  "author": "ruco",
+  "keywords": [
+    "mcp",
+    "model-context-protocol",
+    "sdk",
+    "typescript",
+    "llm",
+    "ai"
+  ],
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/ruco-ai/mcpster"
+  },
+  "type": "module",
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "import": "./dist/index.js",
+      "types": "./dist/index.d.ts"
+    }
+  },
+  "bin": {
+    "mcpster-deploy": "./dist/deploy/cli.js"
+  },
+  "files": [
+    "dist"
+  ],
+  "scripts": {
+    "build": "tsc",
+    "dev": "tsc --watch",
+    "test": "vitest run",
+    "test:watch": "vitest",
+    "prepublishOnly": "npm run build"
+  },
+  "dependencies": {
+    "@modelcontextprotocol/sdk": "^1.29.0",
+    "express": "^5",
+    "zod": "^3"
+  },
+  "devDependencies": {
+    "@types/express": "^5.0.6",
+    "@types/node": "^25.5.2",
+    "typescript": "^5",
+    "vitest": "^4.1.2"
+  }
+}