@eaperezc/mcpgen 0.1.0

package/README.md

@@ -0,0 +1,328 @@
+# mcpkit
+
+A TypeScript framework for building MCP (Model Context Protocol) servers with excellent developer experience.
+
+## Features
+
+- **Class-based API** - Define tools, resources, and prompts using clean class inheritance
+- **Fluent Builder** - Alternative chainable API for simple servers
+- **Built-in Testing** - In-memory test client for unit testing your MCP servers
+- **Structured Logging** - Pino-based logging with correlation IDs
+- **Type-safe** - Full TypeScript support with Zod schema validation
+- **Production Ready** - Supports stdio and HTTP transports
+
+## Installation
+
+```bash
+npm install mcpkit @modelcontextprotocol/sdk
+# or
+pnpm add mcpkit @modelcontextprotocol/sdk
+```
+
+## CLI - Scaffold New Projects
+
+The fastest way to get started is using the CLI:
+
+```bash
+# Install globally
+npm install -g mcpkit
+
+# Create a new project
+mcpkit init my-mcp-server
+
+# Create with HTTP transport
+mcpkit init my-api --transport http
+
+# Navigate and start
+cd my-mcp-server
+npm install
+npm run dev
+```
+
+### Generate Components
+
+```bash
+# Generate a new tool
+mcpkit generate tool search-users
+
+# Generate a new resource
+mcpkit g resource database
+
+# Generate a new prompt
+mcpkit new prompt summarize
+```
+
+### CLI Commands
+
+| Command | Description |
+|---------|-------------|
+| `mcpkit init <name>` | Create a new MCP server project |
+| `mcpkit init <name> --transport http` | Create with HTTP transport |
+| `mcpkit generate tool <name>` | Generate a new tool |
+| `mcpkit generate resource <name>` | Generate a new resource |
+| `mcpkit generate prompt <name>` | Generate a new prompt |
+
+## Quick Start
+
+### Class-based API (Recommended)
+
+```typescript
+import { McpServer, BaseTool, BaseResource } from 'mcpkit';
+import { z } from 'zod';
+
+// Define a tool
+class GreetTool extends BaseTool {
+  name = 'greet';
+  description = 'Greets a user by name';
+
+  schema = z.object({
+    name: z.string().describe('Name to greet'),
+  });
+
+  async execute(input: z.infer<typeof this.schema>) {
+    return { content: { greeting: `Hello, ${input.name}!` } };
+  }
+}
+
+// Define a resource
+class ConfigResource extends BaseResource {
+  uri = 'config://app';
+  name = 'App Configuration';
+
+  async read() {
+    return { contents: [this.json({ version: '1.0.0' })] };
+  }
+}
+
+// Create and start server
+const server = new McpServer({
+  name: 'my-server',
+  version: '1.0.0',
+});
+
+server.tool(new GreetTool());
+server.resource(new ConfigResource());
+server.start();
+```
+
+### Fluent Builder API
+
+```typescript
+import { createServer } from 'mcpkit';
+import { z } from 'zod';
+
+const server = createServer({ name: 'my-server', version: '1.0.0' })
+  .tool('greet', {
+    description: 'Greets a user',
+    schema: z.object({ name: z.string() }),
+    handler: async ({ name }) => ({ content: `Hello, ${name}!` }),
+  })
+  .resource('config://app', {
+    name: 'App Config',
+    read: async () => ({ version: '1.0.0' }),
+  })
+  .build();
+
+await server.start();
+```
+
+## Testing
+
+mcpkit includes a built-in test client for unit testing your MCP servers:
+
+```typescript
+import { describe, it, expect } from 'vitest';
+import { createTestClient } from 'mcpkit/testing';
+import { GreetTool } from './tools/GreetTool';
+
+describe('GreetTool', () => {
+  it('should greet the user', async () => {
+    const client = createTestClient();
+    client.registerTool(new GreetTool());
+
+    const result = await client.callTool('greet', { name: 'Alice' });
+    expect(result.content).toEqual({ greeting: 'Hello, Alice!' });
+  });
+
+  it('should validate input', async () => {
+    const client = createTestClient();
+    client.registerTool(new GreetTool());
+
+    await expect(client.callTool('greet', {})).rejects.toThrow();
+  });
+});
+```
+
+### Testing with Server Builder
+
+```typescript
+import { TestClient } from 'mcpkit/testing';
+import { createServer } from 'mcpkit';
+
+const server = createServer({ name: 'test', version: '1.0.0' })
+  .tool('add', {
+    description: 'Adds numbers',
+    schema: z.object({ a: z.number(), b: z.number() }),
+    handler: async ({ a, b }) => ({ content: { sum: a + b } }),
+  })
+  .build();
+
+const client = TestClient.fromServer(server);
+const result = await client.callTool('add', { a: 2, b: 3 });
+// result.content = { sum: 5 }
+```
+
+## API Reference
+
+### McpServer
+
+```typescript
+const server = new McpServer({
+  name: string;
+  version: string;
+  description?: string;
+  transport?: 'stdio' | TransportConfig;
+  logging?: { level?: 'debug' | 'info' | 'warn' | 'error' };
+});
+
+// Register components
+server.tool(tool: BaseTool);
+server.resource(resource: BaseResource);
+server.prompt(prompt: BasePrompt);
+
+// Lifecycle
+await server.start();
+await server.stop();
+```
+
+### BaseTool
+
+```typescript
+abstract class BaseTool<TSchema extends z.ZodType> {
+  abstract name: string;
+  abstract description: string;
+  abstract schema: TSchema;
+
+  abstract execute(input: z.infer<TSchema>): Promise<ToolResult>;
+}
+```
+
+### BaseResource
+
+```typescript
+abstract class BaseResource {
+  abstract uri: string;
+  abstract name: string;
+  description?: string;
+
+  abstract read(): Promise<ResourceResult>;
+
+  // Helpers
+  protected text(content: string): ResourceContent;
+  protected json(data: unknown): ResourceContent;
+}
+```
+
+### BasePrompt
+
+```typescript
+abstract class BasePrompt<TArgs extends z.ZodType> {
+  abstract name: string;
+  description?: string;
+  arguments?: TArgs;
+
+  abstract render(args: z.infer<TArgs>): Promise<PromptResult>;
+
+  // Helpers
+  protected user(content: string): PromptMessage;
+  protected assistant(content: string): PromptMessage;
+}
+```
+
+## Project Structure
+
+When building MCP servers with mcpkit, we recommend:
+
+```
+my-mcp-server/
+├── src/
+│   ├── tools/
+│   │   ├── GreetTool.ts
+│   │   └── index.ts
+│   ├── resources/
+│   │   ├── ConfigResource.ts
+│   │   └── index.ts
+│   ├── prompts/
+│   │   └── index.ts
+│   └── index.ts
+├── tests/
+│   └── tools.test.ts
+├── package.json
+└── tsconfig.json
+```
+
+## HTTP Transport
+
+mcpkit supports HTTP transport for remote MCP servers:
+
+```typescript
+import { McpServer } from 'mcpkit';
+
+const server = new McpServer({
+  name: 'my-http-server',
+  version: '1.0.0',
+  transport: {
+    type: 'http',
+    port: 3000,
+    host: '0.0.0.0', // Optional, defaults to 0.0.0.0
+    basePath: '/mcp', // Optional, defaults to /mcp
+    cors: {
+      origin: ['https://myapp.com'],
+      credentials: true,
+    },
+  },
+});
+
+server.tool(new MyTool());
+await server.start();
+
+// Server is now running at http://0.0.0.0:3000/mcp
+// Health check available at http://0.0.0.0:3000/health
+```
+
+### CORS Configuration
+
+```typescript
+{
+  transport: {
+    type: 'http',
+    port: 3000,
+    cors: {
+      origin: '*', // or ['https://example.com']
+      methods: ['GET', 'POST', 'OPTIONS'],
+      allowedHeaders: ['Content-Type', 'Authorization'],
+      credentials: true,
+      maxAge: 86400,
+    },
+  },
+}
+```
+
+## Roadmap
+
+- [x] Core server implementation
+- [x] Tools, Resources, Prompts
+- [x] Stdio transport
+- [x] HTTP transport (production-ready)
+- [x] Testing utilities
+- [x] Structured logging
+- [x] CLI scaffolding (`mcpkit init`, `mcpkit generate`)
+- [ ] SSE transport
+- [ ] OAuth 2.1 authentication
+- [ ] API key authentication
+- [ ] Middleware system
+- [ ] Auto-discovery
+
+## License
+
+MIT