github-to-mcp-monorepo 1.0.0

package/packages/core/src/types.ts

@@ -0,0 +1,289 @@
+/**
+ * @fileoverview Type definitions and interfaces
+ * @copyright Copyright (c) 2024-2026 nirholas
+ * @license MIT
+ */
+
+/**
+ * Types for GitHub to MCP Generator
+ */
+
+export type SourceType = 'readme' | 'openapi' | 'graphql' | 'grpc' | 'code' | 'mcp-introspect' | 'tests' | 'docs' | 'examples' | 'universal';
+
+export type NamingStyle = 'camelCase' | 'snake_case' | 'kebab-case' | 'PascalCase';
+
+export type OutputLanguage = 'typescript' | 'python' | 'go';
+
+/**
+ * Classification of repository type
+ */
+export type RepoType = 
+  | 'api-sdk'      // API client/SDK with extractable endpoints
+  | 'mcp-server'   // Already an MCP server
+  | 'cli-tool'     // Command-line tool
+  | 'library'      // Code library/package
+  | 'documentation' // Docs, tutorials, guides
+  | 'data'         // Datasets, configs
+  | 'unknown';     // Fallback
+
+export interface RepoClassification {
+  type: RepoType;
+  confidence: number; // 0-1
+  indicators: string[];
+}
+
+export interface GithubToMcpOptions {
+  // Sources to extract from
+  sources?: SourceType[];
+
+  // Follow documentation links
+  followDocs?: boolean;
+  depth?: number;
+
+  // Include code examples
+  includeExamples?: boolean;
+
+  // Generate tests
+  generateTests?: boolean;
+
+  // Output format
+  outputFormat?: 'typescript' | 'javascript';
+  
+  // Output language (typescript or python)
+  outputLanguage?: OutputLanguage;
+
+  // Naming convention
+  naming?: {
+    prefix?: string;
+    suffix?: string;
+    style?: NamingStyle;
+  };
+
+  // Authentication
+  githubToken?: string;
+
+  // Caching
+  cache?: boolean;
+  cacheDir?: string;
+  cacheTTL?: {
+    metadata?: number;  // TTL for repo metadata in seconds (default: 3600)
+    files?: number;     // TTL for file contents in seconds (default: 900)
+  };
+
+  // Rate limiting
+  rateLimit?: {
+    maxRequests: number;
+    perSeconds: number;
+  };
+
+  // Output directory
+  outputDir?: string;
+
+  // Verbose logging
+  verbose?: boolean;
+}
+
+/**
+ * Confidence factors for tool extraction
+ */
+export interface ConfidenceFactors {
+  documentation: number; // 0-1: completeness of description, params, returns
+  types: number;         // 0-1: type information availability
+  examples: number;      // 0-1: presence of examples
+  source: number;        // 0-1: reliability of source (README vs code comments)
+}
+
+export interface ExtractedTool {
+  name: string;
+  description: string;
+  inputSchema: any;
+  implementation?: string;
+  examples?: string[];
+  source: {
+    type: SourceType;
+    file: string;
+    line?: number;
+  };
+  confidence?: number;           // 0-1 overall confidence score
+  confidenceFactors?: ConfidenceFactors;
+}
+
+export interface SourceBreakdown {
+  type: SourceType;
+  count: number;
+  files: string[];
+}
+
+export interface GenerationResult {
+  repo: string;
+  name: string;
+  tools: ExtractedTool[];
+  sources: SourceBreakdown[];
+  classification: RepoClassification;
+  metadata: {
+    stars: number;
+    language: string;
+    license?: string;
+    description?: string;
+  };
+  
+  // Methods
+  generate(): string;
+  generatePython?(): string;
+  save(outputDir: string): Promise<void>;
+  download(): void;
+}
+
+export interface RepoMetadata {
+  owner: string;
+  repo: string;
+  branch?: string;
+  path?: string;
+}
+
+export interface FileContent {
+  path: string;
+  content: string;
+  type: 'file' | 'dir';
+  sha: string;
+}
+
+export interface ApiSpec {
+  type: 'openapi' | 'swagger' | 'postman' | 'graphql';
+  version: string;
+  spec: any;
+  path: string;
+}
+
+export interface GraphQLSchema {
+  queries: GraphQLOperation[];
+  mutations: GraphQLOperation[];
+  subscriptions: GraphQLOperation[];
+  types: Record<string, GraphQLType>;
+}
+
+export interface GraphQLOperation {
+  name: string;
+  description?: string;
+  args: GraphQLArg[];
+  returnType: string;
+}
+
+export interface GraphQLArg {
+  name: string;
+  type: string;
+  required: boolean;
+  description?: string;
+}
+
+export interface GraphQLType {
+  name: string;
+  kind: 'object' | 'enum' | 'scalar' | 'input';
+  fields?: Array<{ name: string; type: string; description?: string }>;
+  values?: string[];
+}
+
+export interface McpToolDefinition {
+  name: string;
+  description: string;
+  inputSchema: {
+    type: 'object';
+    properties: Record<string, any>;
+    required: string[];
+  };
+}
+
+export interface CodeExample {
+  code: string;
+  language: string;
+  description?: string;
+  file: string;
+  line: number;
+}
+
+export interface DocumentationLink {
+  url: string;
+  title?: string;
+  source: string;
+}
+
+export interface SdkMethod {
+  name: string;
+  parameters: Array<{
+    name: string;
+    type: string;
+    required: boolean;
+    description?: string;
+  }>;
+  returnType: string;
+  description?: string;
+  file: string;
+  line: number;
+}
+
+/**
+ * Monorepo detection types
+ */
+export type MonorepoType = 
+  | 'lerna'           // lerna.json
+  | 'nx'              // nx.json
+  | 'turborepo'       // turbo.json
+  | 'pnpm'            // pnpm-workspace.yaml
+  | 'yarn'            // workspaces in package.json
+  | 'npm'             // workspaces in package.json
+  | 'custom'          // packages/*, apps/*, libs/*
+  | 'none';           // Not a monorepo
+
+export interface MonorepoInfo {
+  type: MonorepoType;
+  packages: MonorepoPackage[];
+  rootPath: string;
+}
+
+export interface MonorepoPackage {
+  name: string;
+  path: string;
+  language?: string;
+}
+
+/**
+ * Cache entry for GitHub API responses
+ */
+export interface CacheEntry<T> {
+  data: T;
+  timestamp: number;
+  ttl: number;
+  etag?: string;
+}
+
+/**
+ * Cache adapter interface for pluggable storage
+ */
+export interface CacheAdapter {
+  get<T>(key: string): Promise<CacheEntry<T> | null>;
+  set<T>(key: string, entry: CacheEntry<T>): Promise<void>;
+  delete(key: string): Promise<void>;
+  clear(): Promise<void>;
+}
+
+/**
+ * Parsed documentation from various languages
+ */
+export interface ParsedDocumentation {
+  description?: string;
+  params: Array<{
+    name: string;
+    type?: string;
+    description?: string;
+    required?: boolean;
+    defaultValue?: any;
+  }>;
+  returns?: {
+    type?: string;
+    description?: string;
+  };
+  examples?: string[];
+  throws?: string[];
+  deprecated?: boolean;
+  since?: string;
+}

package/packages/core/tsconfig.json

@@ -0,0 +1,9 @@
+{
+  "extends": "../../tsconfig.json",
+  "compilerOptions": {
+    "outDir": "./dist",
+    "rootDir": "./src"
+  },
+  "include": ["src/**/*"],
+  "exclude": ["node_modules", "dist"]
+}

package/packages/core/tsup.config.ts

@@ -0,0 +1,25 @@
+import { defineConfig } from 'tsup';
+
+export default [
+  // Library build
+  defineConfig({
+    entry: ['src/index.ts'],
+    format: ['esm'],
+    dts: false, // Disabled due to openapi-parser type conflicts
+    sourcemap: true,
+    clean: true,
+    target: 'es2022',
+    outExtension: () => ({ js: '.mjs' }),
+  }),
+  // CLI build  
+  defineConfig({
+    entry: ['src/cli.ts'],
+    format: ['esm'],
+    sourcemap: true,
+    target: 'es2022',
+    outExtension: () => ({ js: '.mjs' }),
+    banner: {
+      js: '#!/usr/bin/env node',
+    },
+  }),
+];

package/packages/mcp-server/README.md

@@ -0,0 +1,297 @@
+# @github-to-mcp/mcp-server
+
+MCP server that exposes github-to-mcp functionality for AI assistants like Claude Desktop and Cursor.
+
+## Overview
+
+This MCP server allows AI assistants to convert GitHub repositories into MCP servers on demand. It's the meta layer - using MCP to create MCP servers!
+
+## Installation
+
+```bash
+# Install globally
+npm install -g @github-to-mcp/mcp-server
+
+# Or use npx
+npx @github-to-mcp/mcp-server
+```
+
+## Configuration
+
+### Claude Desktop
+
+Add to `~/Library/Application Support/Claude/claude_desktop_config.json` (macOS):
+
+```json
+{
+  "mcpServers": {
+    "github-to-mcp": {
+      "command": "npx",
+      "args": ["-y", "@github-to-mcp/mcp-server"],
+      "env": {
+        "GITHUB_TOKEN": "your-github-token"
+      }
+    }
+  }
+}
+```
+
+### Cursor
+
+Add to `.cursor/mcp.json`:
+
+```json
+{
+  "mcpServers": {
+    "github-to-mcp": {
+      "command": "npx",
+      "args": ["-y", "@github-to-mcp/mcp-server"]
+    }
+  }
+}
+```
+
+## Available Tools
+
+### `convert_repo`
+
+Convert a GitHub repository into a complete MCP server implementation.
+
+```
+Arguments:
+- github_url (required): The GitHub repository URL
+- output_language: "typescript" or "python" (default: typescript)
+- sources: Array of extraction sources to use
+- github_token: GitHub token for private repos
+```
+
+### `list_extracted_tools`
+
+Preview what tools would be extracted from a repository without generating the full server.
+
+```
+Arguments:
+- github_url (required): The GitHub repository URL
+- sources: Array of extraction sources
+- github_token: GitHub token (optional)
+```
+
+### `validate_mcp_server`
+
+Validate MCP server code for correctness and best practices.
+
+```
+Arguments:
+- code (required): The MCP server code to validate
+- language (required): "typescript" or "python"
+```
+
+### `generate_claude_config`
+
+Generate Claude Desktop configuration for an MCP server.
+
+```
+Arguments:
+- server_name (required): Name for the server
+- server_path (required): Path to the server file
+- language (required): "typescript" or "python"
+- env_vars: Environment variables to pass
+```
+
+### `generate_cursor_config`
+
+Generate Cursor IDE configuration for an MCP server.
+
+```
+Arguments:
+- server_name (required): Name for the server
+- server_path (required): Path to the server file
+- language (required): "typescript" or "python"
+```
+
+### `analyze_repo_structure`
+
+Analyze a repository to identify extraction sources and capabilities.
+
+```
+Arguments:
+- github_url (required): The GitHub repository URL
+- github_token: GitHub token (optional)
+```
+
+### `convert_openapi_to_mcp`
+
+Convert an OpenAPI/Swagger specification directly to MCP tools.
+
+```
+Arguments:
+- spec (required): The OpenAPI spec content (JSON or YAML)
+- format: openapi, swagger, postman, insomnia, har, asyncapi, graphql
+- base_url: Override base URL for API calls
+```
+
+### `get_tool_template`
+
+Get a starter template for creating a new MCP tool.
+
+```
+Arguments:
+- tool_name (required): Name for the tool
+- description (required): What the tool does
+- parameters: Array of parameter definitions
+- language: "typescript" or "python"
+```
+
+### `generate_openapi_spec`
+
+Generate OpenAPI 3.1 specification from source code (reverse engineering).
+
+```
+Arguments:
+- files (required): Array of source files to analyze
+  - path: File path
+  - content: File content
+- format: Output format ("json", "yaml", or "both")
+- options: Generation options
+  - title: API title
+  - version: API version
+  - baseUrl: Base URL for the API
+  - servers: Array of server configurations
+```
+
+**Example:**
+```json
+{
+  "files": [
+    {
+      "path": "routes/users.js",
+      "content": "app.get('/users', (req, res) => { ... })"
+    }
+  ],
+  "format": "both",
+  "options": {
+    "title": "My API",
+    "version": "1.0.0"
+  }
+}
+```
+
+### `export_docker`
+
+Generate Docker configuration files for deploying an MCP server.
+
+```
+Arguments:
+- language (required): "typescript" or "python"
+- server_name: Custom name for the server (default: "mcp-server")
+- port: Port number for the server
+- include_healthcheck: Include Docker healthcheck (default: false)
+- env_vars: Environment variables as key-value pairs
+```
+
+**Example:**
+```json
+{
+  "language": "typescript",
+  "server_name": "my-mcp-server",
+  "port": 3000,
+  "include_healthcheck": true,
+  "env_vars": {
+    "API_KEY": "secret",
+    "DEBUG": "true"
+  }
+}
+```
+
+Returns Dockerfile, docker-compose.yml, and .dockerignore files.
+
+### `stream_convert`
+
+Convert a GitHub repository with real-time progress updates (streaming).
+
+```
+Arguments:
+- github_url (required): GitHub repository URL
+- output_language: "typescript" or "python"
+- sources: Array of extraction sources
+- github_token: GitHub token for private repos
+```
+
+Returns a stream of progress events showing:
+- Repository cloning
+- File analysis
+- Tool extraction
+- Code generation
+
+### `list_providers`
+
+List all supported AI providers and their MCP configuration formats.
+
+```
+Arguments:
+- include_examples: Include example configurations (default: true)
+```
+
+Returns information about:
+- Claude Desktop
+- Cursor
+- VS Code Copilot
+- Continue
+- Cline
+- Windsurf
+- And more...
+
+Each provider includes configuration path, format, and example setup.
+
+## Available Resources
+
+The server also provides documentation resources:
+
+- `github-to-mcp://docs/quick-start` - Quick start guide
+- `github-to-mcp://docs/extraction-sources` - Extraction source documentation
+- `github-to-mcp://examples/typescript` - TypeScript MCP server example
+- `github-to-mcp://examples/python` - Python MCP server example
+
+## Example Usage
+
+### With Claude Desktop
+
+Once configured, you can ask Claude:
+
+> "Convert the microsoft/playwright GitHub repo into an MCP server"
+
+Claude will use the `convert_repo` tool to generate a complete MCP server implementation.
+
+> "What tools can be extracted from the fastapi/fastapi repository?"
+
+Claude will use `list_extracted_tools` to show you the available tools.
+
+### Direct Execution
+
+```bash
+# Run the MCP server
+github-to-mcp-server
+
+# With environment variables
+GITHUB_TOKEN=your-token github-to-mcp-server
+```
+
+## Development
+
+```bash
+# Install dependencies
+pnpm install
+
+# Build
+pnpm build
+
+# Run in development
+pnpm dev
+
+# Run tests
+pnpm test
+```
+
+## License
+
+MIT - See [LICENSE](../../LICENSE) for details.

package/packages/mcp-server/package.json

@@ -0,0 +1,55 @@
+{
+  "name": "@github-to-mcp/mcp-server",
+  "version": "1.0.0",
+  "description": "MCP server exposing github-to-mcp functionality for AI assistants",
+  "type": "module",
+  "main": "./dist/index.mjs",
+  "module": "./dist/index.mjs",
+  "types": "./dist/index.d.mts",
+  "bin": {
+    "github-to-mcp-server": "./dist/index.mjs"
+  },
+  "exports": {
+    ".": {
+      "import": "./dist/index.mjs",
+      "types": "./dist/index.d.mts"
+    }
+  },
+  "files": [
+    "dist"
+  ],
+  "scripts": {
+    "build": "tsup",
+    "dev": "tsup --watch",
+    "start": "node dist/index.mjs",
+    "typecheck": "tsc --noEmit",
+    "test": "vitest run",
+    "test:watch": "vitest"
+  },
+  "keywords": [
+    "mcp",
+    "model-context-protocol",
+    "github",
+    "ai",
+    "tools",
+    "server"
+  ],
+  "author": "nirholas",
+  "license": "Apache-2.0",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/nirholas/github-to-mcp"
+  },
+  "dependencies": {
+    "@nirholas/github-to-mcp": "workspace:*",
+    "@github-to-mcp/openapi-parser": "workspace:*",
+    "@modelcontextprotocol/sdk": "^1.0.0",
+    "zod": "^3.23.0"
+  },
+  "devDependencies": {
+    "@types/node": "^20.10.0",
+    "tsup": "^8.0.0",
+    "typescript": "^5.3.0",
+    "vitest": "^1.0.0"
+  }
+}