github-to-mcp-monorepo 1.0.0

package/mkdocs/docs/api/mcp-server.md

@@ -0,0 +1,301 @@
+# MCP Server
+
+The `@github-to-mcp/mcp-server` package provides the MCP server implementation.
+
+## Installation
+
+```bash
+npm install @github-to-mcp/mcp-server
+```
+
+## Creating a Server
+
+### Basic Usage
+
+```typescript
+import { createMcpServer } from '@github-to-mcp/mcp-server';
+
+const server = createMcpServer({
+  name: 'my-mcp-server',
+  version: '1.0.0',
+  tools: [
+    {
+      name: 'hello_world',
+      description: 'Say hello',
+      inputSchema: {
+        type: 'object',
+        properties: {
+          name: { type: 'string' }
+        }
+      },
+      execute: async ({ name }) => {
+        return { greeting: `Hello, ${name}!` };
+      }
+    }
+  ]
+});
+
+await server.start();
+```
+
+### With Generated Tools
+
+```typescript
+import { createMcpServer } from '@github-to-mcp/mcp-server';
+import { generateFromGithub } from '@nirholas/github-to-mcp';
+
+const result = await generateFromGithub('https://github.com/owner/repo');
+
+const server = createMcpServer({
+  name: 'repo-mcp',
+  version: '1.0.0',
+  tools: result.tools.map(tool => ({
+    ...tool,
+    execute: createExecutor(tool),
+  })),
+});
+
+await server.start();
+```
+
+---
+
+## Server Options
+
+### McpServerOptions
+
+```typescript
+interface McpServerOptions {
+  /** Server name */
+  name: string;
+  
+  /** Server version */
+  version: string;
+  
+  /** Tool definitions */
+  tools: ToolDefinition[];
+  
+  /** Transport type */
+  transport?: 'stdio' | 'http';
+  
+  /** HTTP port (if using http transport) */
+  port?: number;
+  
+  /** Enable logging */
+  logging?: boolean;
+  
+  /** Custom logger */
+  logger?: Logger;
+}
+```
+
+---
+
+## Transport Modes
+
+### Stdio (Default)
+
+For process-based communication with AI clients:
+
+```typescript
+const server = createMcpServer({
+  name: 'my-server',
+  transport: 'stdio',
+  tools: [...]
+});
+
+await server.start();
+// Communicates via stdin/stdout
+```
+
+### HTTP
+
+For network-based communication:
+
+```typescript
+const server = createMcpServer({
+  name: 'my-server',
+  transport: 'http',
+  port: 3000,
+  tools: [...]
+});
+
+await server.start();
+// Listening on http://localhost:3000
+```
+
+---
+
+## Tool Definition
+
+### ToolDefinition
+
+```typescript
+interface ToolDefinition {
+  /** Tool name (snake_case recommended) */
+  name: string;
+  
+  /** Human-readable description */
+  description: string;
+  
+  /** JSON Schema for input parameters */
+  inputSchema: JSONSchema;
+  
+  /** Tool execution function */
+  execute: (input: unknown, context: ToolContext) => Promise<unknown>;
+}
+```
+
+### ToolContext
+
+```typescript
+interface ToolContext {
+  /** Server configuration */
+  config: ServerConfig;
+  
+  /** Logger instance */
+  logger: Logger;
+  
+  /** Access to other tools */
+  tools: Record<string, ToolDefinition>;
+  
+  /** Request metadata */
+  request: RequestMetadata;
+}
+```
+
+---
+
+## Server Methods
+
+### start()
+
+Start the MCP server.
+
+```typescript
+await server.start();
+```
+
+### stop()
+
+Stop the MCP server.
+
+```typescript
+await server.stop();
+```
+
+### addTool()
+
+Add a tool dynamically.
+
+```typescript
+server.addTool({
+  name: 'new_tool',
+  description: 'A new tool',
+  inputSchema: { type: 'object' },
+  execute: async () => ({ result: 'ok' }),
+});
+```
+
+### removeTool()
+
+Remove a tool.
+
+```typescript
+server.removeTool('tool_name');
+```
+
+### listTools()
+
+List all registered tools.
+
+```typescript
+const tools = server.listTools();
+console.log(tools.map(t => t.name));
+```
+
+---
+
+## Error Handling
+
+### ToolError
+
+Throw to return an error to the client:
+
+```typescript
+import { ToolError } from '@github-to-mcp/mcp-server';
+
+const tool = {
+  name: 'risky_operation',
+  execute: async ({ path }) => {
+    if (path.includes('..')) {
+      throw new ToolError('Invalid path: directory traversal not allowed');
+    }
+    // ...
+  }
+};
+```
+
+### Error Codes
+
+```typescript
+enum ErrorCode {
+  InvalidParams = -32602,
+  InternalError = -32603,
+  ToolNotFound = -32001,
+  ExecutionFailed = -32002,
+}
+```
+
+---
+
+## Middleware
+
+Add middleware for cross-cutting concerns:
+
+```typescript
+const server = createMcpServer({
+  name: 'my-server',
+  tools: [...],
+  middleware: [
+    // Logging middleware
+    async (tool, input, context, next) => {
+      console.log(`Calling ${tool.name} with`, input);
+      const start = Date.now();
+      const result = await next();
+      console.log(`${tool.name} completed in ${Date.now() - start}ms`);
+      return result;
+    },
+    
+    // Caching middleware
+    async (tool, input, context, next) => {
+      const cacheKey = `${tool.name}:${JSON.stringify(input)}`;
+      const cached = cache.get(cacheKey);
+      if (cached) return cached;
+      const result = await next();
+      cache.set(cacheKey, result);
+      return result;
+    },
+  ],
+});
+```
+
+---
+
+## Protocol Compliance
+
+This server implements the [Model Context Protocol](https://modelcontextprotocol.io) specification:
+
+- **JSON-RPC 2.0** communication
+- **tools/list** - List available tools
+- **tools/call** - Execute a tool
+- **resources/list** - List resources (optional)
+- **prompts/list** - List prompts (optional)
+
+---
+
+## See Also
+
+- [Core API](core.md) - Main library
+- [Claude Desktop](../guides/claude-desktop.md) - Integration guide
+- [MCP Protocol](../concepts/mcp-protocol.md) - Protocol details

package/mkdocs/docs/api/openapi-parser.md

@@ -0,0 +1,254 @@
+# OpenAPI Parser
+
+The `@github-to-mcp/openapi-parser` package extracts tools from OpenAPI/Swagger and GraphQL schemas.
+
+## Installation
+
+```bash
+npm install @github-to-mcp/openapi-parser
+```
+
+## Functions
+
+### parseOpenAPI
+
+Parse an OpenAPI specification and extract tools.
+
+```typescript
+function parseOpenAPI(
+  spec: string | object,
+  options?: OpenAPIParserOptions
+): Promise<Tool[]>
+```
+
+#### Example
+
+```typescript
+import { parseOpenAPI } from '@github-to-mcp/openapi-parser';
+
+const spec = await fs.readFile('openapi.json', 'utf-8');
+const tools = await parseOpenAPI(spec);
+
+console.log(`Extracted ${tools.length} tools from OpenAPI spec`);
+```
+
+---
+
+### parseGraphQL
+
+Parse a GraphQL schema and extract tools.
+
+```typescript
+function parseGraphQL(
+  schema: string,
+  options?: GraphQLParserOptions
+): Promise<Tool[]>
+```
+
+#### Example
+
+```typescript
+import { parseGraphQL } from '@github-to-mcp/openapi-parser';
+
+const schema = await fs.readFile('schema.graphql', 'utf-8');
+const tools = await parseGraphQL(schema, {
+  includeQueries: true,
+  includeMutations: true,
+  includeSubscriptions: false,
+});
+
+console.log(`Extracted ${tools.length} tools from GraphQL schema`);
+```
+
+---
+
+### findSpecs
+
+Find OpenAPI and GraphQL specs in a file tree.
+
+```typescript
+function findSpecs(
+  files: FileTree,
+  options?: FindSpecsOptions
+): SpecFiles
+```
+
+#### Example
+
+```typescript
+import { findSpecs } from '@github-to-mcp/openapi-parser';
+
+const specs = findSpecs(fileTree, {
+  maxDepth: 3,
+  patterns: ['**/openapi.{json,yaml}', '**/swagger.{json,yaml}'],
+});
+
+console.log(`Found ${specs.openapi.length} OpenAPI specs`);
+console.log(`Found ${specs.graphql.length} GraphQL schemas`);
+```
+
+---
+
+## Types
+
+### OpenAPIParserOptions
+
+```typescript
+interface OpenAPIParserOptions {
+  /** Include all operations or filter */
+  includeOperations?: string[];
+  
+  /** Exclude specific operations */
+  excludeOperations?: string[];
+  
+  /** Include deprecated operations */
+  includeDeprecated?: boolean;
+  
+  /** Custom operation ID generator */
+  operationIdGenerator?: (operation: Operation) => string;
+  
+  /** Base URL for API calls */
+  baseUrl?: string;
+}
+```
+
+### GraphQLParserOptions
+
+```typescript
+interface GraphQLParserOptions {
+  /** Include query operations */
+  includeQueries?: boolean;
+  
+  /** Include mutation operations */
+  includeMutations?: boolean;
+  
+  /** Include subscription operations */
+  includeSubscriptions?: boolean;
+  
+  /** Include deprecated fields */
+  includeDeprecated?: boolean;
+}
+```
+
+### SpecFiles
+
+```typescript
+interface SpecFiles {
+  /** Found OpenAPI specifications */
+  openapi: Array<{
+    path: string;
+    version: '2.0' | '3.0' | '3.1';
+    content: string;
+  }>;
+  
+  /** Found GraphQL schemas */
+  graphql: Array<{
+    path: string;
+    content: string;
+  }>;
+}
+```
+
+---
+
+## OpenAPI Support
+
+### Supported Versions
+
+| Version | Support |
+|---------|---------|
+| OpenAPI 3.1 | ✅ Full |
+| OpenAPI 3.0 | ✅ Full |
+| Swagger 2.0 | ✅ Full |
+
+### Supported Formats
+
+| Format | Extensions |
+|--------|------------|
+| JSON | `.json` |
+| YAML | `.yaml`, `.yml` |
+
+### Extracted Information
+
+For each operation, the parser extracts:
+
+- Operation ID (or generates one)
+- HTTP method and path
+- Description and summary
+- Request parameters (path, query, header)
+- Request body schema
+- Response schemas
+- Security requirements
+
+---
+
+## GraphQL Support
+
+### Supported Features
+
+- Queries
+- Mutations
+- Subscriptions (optional)
+- Input types
+- Custom scalars
+- Directives
+
+### Schema Introspection
+
+```typescript
+import { introspectGraphQL } from '@github-to-mcp/openapi-parser';
+
+const schema = await introspectGraphQL('https://api.example.com/graphql');
+const tools = await parseGraphQL(schema);
+```
+
+---
+
+## Advanced Usage
+
+### Custom Tool Naming
+
+```typescript
+const tools = await parseOpenAPI(spec, {
+  operationIdGenerator: (op) => {
+    // Custom naming: method_path
+    return `${op.method}_${op.path.replace(/\//g, '_')}`;
+  },
+});
+```
+
+### Filtering Operations
+
+```typescript
+// Only include specific operations
+const tools = await parseOpenAPI(spec, {
+  includeOperations: ['createUser', 'getUser', 'updateUser'],
+});
+
+// Exclude deprecated
+const tools = await parseOpenAPI(spec, {
+  includeDeprecated: false,
+});
+```
+
+### Combining Multiple Specs
+
+```typescript
+import { parseOpenAPI, mergeTools } from '@github-to-mcp/openapi-parser';
+
+const spec1Tools = await parseOpenAPI(spec1);
+const spec2Tools = await parseOpenAPI(spec2);
+
+const allTools = mergeTools([spec1Tools, spec2Tools], {
+  deduplicateBy: 'name',
+  conflictResolution: 'rename',
+});
+```
+
+---
+
+## See Also
+
+- [Core API](core.md) - Main library
+- [Tool Types](../concepts/tool-types.md) - Understanding extracted tools
+- [How It Works](../concepts/how-it-works.md) - Extraction process

package/mkdocs/docs/assets/logo.svg

@@ -0,0 +1,7 @@
+<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 100 100" fill="none">
+  <rect width="100" height="100" rx="16" fill="#000"/>
+  <path d="M50 20C33.4 20 20 33.4 20 50C20 63.3 28.7 74.5 40.7 78.4C42.2 78.7 42.8 77.8 42.8 77C42.8 76.3 42.8 74.5 42.8 72.1C34.1 74.1 32.3 67.4 32.3 67.4C30.9 63.9 28.9 63 28.9 63C26.1 61.1 29.1 61.1 29.1 61.1C32.2 61.3 33.8 64.3 33.8 64.3C36.5 69.1 41 67.5 42.9 66.8C43.2 64.8 44 63.5 44.9 62.7C38 62 30.8 59.5 30.8 48.1C30.8 44.8 32 42.1 33.9 40C33.5 39.2 32.6 36.1 34.2 31.9C34.2 31.9 36.8 31.1 42.8 35.1C45.2 34.4 47.7 34.1 50.2 34.1C52.7 34.1 55.2 34.4 57.6 35.1C63.5 31 66.2 31.9 66.2 31.9C67.8 36.1 66.9 39.2 66.5 40C68.4 42.1 69.6 44.9 69.6 48.1C69.6 59.6 62.3 62 55.4 62.7C56.5 63.7 57.5 65.6 57.5 68.5C57.5 72.7 57.5 76 57.5 77C57.5 77.8 58.1 78.8 59.6 78.5C71.5 74.6 80.2 63.4 80.2 50.1C80 33.4 66.6 20 50 20Z" fill="#fff"/>
+  <path d="M65 55L75 65L85 55" stroke="#fff" stroke-width="4" stroke-linecap="round" stroke-linejoin="round"/>
+  <circle cx="80" cy="75" r="8" stroke="#fff" stroke-width="3" fill="none"/>
+  <path d="M80 70V80M75 75H85" stroke="#fff" stroke-width="2" stroke-linecap="round"/>
+</svg>

package/mkdocs/docs/changelog.md

@@ -0,0 +1,118 @@
+# Changelog
+
+All notable changes to GitHub to MCP.
+
+## [1.0.0] - 2025-01-17
+
+### 🎉 Initial Release
+
+First stable release of GitHub to MCP!
+
+### Features
+
+- **Core Conversion** - Convert any GitHub repository to MCP server
+- **Web Interface** - Browser-based conversion at [github-to-mcp.vercel.app](https://github-to-mcp.vercel.app)
+- **CLI Tool** - Command-line interface for automation
+- **Programmatic API** - JavaScript/TypeScript library
+
+### Universal Tools
+
+Every generated server includes:
+
+- `get_readme` - Fetch repository README
+- `list_files` - Browse directory structure
+- `read_file` - Read file contents
+- `search_code` - Search for code patterns
+
+### Extraction Sources
+
+- **OpenAPI/Swagger** - Extract REST API endpoints
+- **GraphQL** - Extract queries and mutations
+- **MCP Servers** - Parse existing tool definitions
+- **Code Analysis** - Detect patterns in source code
+
+### Output Formats
+
+- TypeScript MCP servers
+- Python MCP servers (experimental)
+
+### Integrations
+
+- Claude Desktop configuration
+- Cursor IDE support
+- Continue extension support
+
+---
+
+## [0.9.0] - 2025-01-10 (Beta)
+
+### Added
+
+- GraphQL schema parsing
+- Python output support
+- Batch conversion feature
+- Playground for testing tools
+
+### Changed
+
+- Improved OpenAPI parsing accuracy
+- Better error messages
+- Faster generation times
+
+### Fixed
+
+- Rate limit handling
+- Large repository support
+- Unicode file handling
+
+---
+
+## [0.8.0] - 2025-01-03 (Alpha)
+
+### Added
+
+- Initial CLI implementation
+- OpenAPI extraction
+- Basic web interface
+
+### Known Issues
+
+- GraphQL not yet supported
+- Limited error handling
+- No Python output
+
+---
+
+## Versioning
+
+This project follows [Semantic Versioning](https://semver.org/):
+
+- **MAJOR** - Breaking changes to public API
+- **MINOR** - New features, backward compatible
+- **PATCH** - Bug fixes, backward compatible
+
+---
+
+## Upgrade Guide
+
+### From 0.x to 1.0
+
+No breaking changes! Simply update your dependency:
+
+```bash
+npm install @nirholas/github-to-mcp@latest
+```
+
+---
+
+## Release Schedule
+
+- **Major releases**: As needed for breaking changes
+- **Minor releases**: Monthly feature releases
+- **Patch releases**: As needed for bug fixes
+
+---
+
+## Contributing
+
+Want to contribute to the next release? See our [Contributing Guide](contributing/index.md)!