github-to-mcp-monorepo 1.0.0

package/mkdocs/docs/concepts/tool-types.md

@@ -0,0 +1,382 @@
+# Tool Types
+
+Understanding the different types of tools generated by GitHub to MCP.
+
+## Overview
+
+Tools are the core functionality exposed by MCP servers. GitHub to MCP generates two categories:
+
+1. **Universal Tools** - Always included, work with any repository
+2. **Extracted Tools** - Specific to the repository's API/functionality
+
+## Universal Tools
+
+These tools are included by default for every repository.
+
+### get_readme
+
+Fetch the repository's README content.
+
+```json
+{
+  "name": "get_readme",
+  "description": "Get the README content of the repository",
+  "inputSchema": {
+    "type": "object",
+    "properties": {}
+  }
+}
+```
+
+**Use case**: Understanding what a project does, finding documentation.
+
+### list_files
+
+List files and directories in the repository.
+
+```json
+{
+  "name": "list_files",
+  "description": "List files in a directory",
+  "inputSchema": {
+    "type": "object",
+    "properties": {
+      "path": {
+        "type": "string",
+        "description": "Directory path (default: root)"
+      },
+      "recursive": {
+        "type": "boolean",
+        "description": "Include subdirectories"
+      }
+    }
+  }
+}
+```
+
+**Use case**: Exploring project structure, finding specific files.
+
+### read_file
+
+Read the contents of any file.
+
+```json
+{
+  "name": "read_file",
+  "description": "Read the contents of a file",
+  "inputSchema": {
+    "type": "object",
+    "properties": {
+      "path": {
+        "type": "string",
+        "description": "Path to the file"
+      }
+    },
+    "required": ["path"]
+  }
+}
+```
+
+**Use case**: Reading source code, configuration files, documentation.
+
+### search_code
+
+Search for code patterns in the repository.
+
+```json
+{
+  "name": "search_code",
+  "description": "Search for code patterns",
+  "inputSchema": {
+    "type": "object",
+    "properties": {
+      "query": {
+        "type": "string",
+        "description": "Search query"
+      },
+      "path": {
+        "type": "string",
+        "description": "Limit search to path"
+      },
+      "extension": {
+        "type": "string",
+        "description": "File extension filter"
+      }
+    },
+    "required": ["query"]
+  }
+}
+```
+
+**Use case**: Finding function definitions, usages, patterns.
+
+---
+
+## Extracted Tools
+
+These tools are specific to each repository, extracted from various sources.
+
+### From OpenAPI/Swagger
+
+API endpoints become callable tools:
+
+**Original OpenAPI:**
+```yaml
+paths:
+  /customers:
+    post:
+      operationId: createCustomer
+      summary: Create a new customer
+      requestBody:
+        content:
+          application/json:
+            schema:
+              type: object
+              properties:
+                email:
+                  type: string
+                name:
+                  type: string
+```
+
+**Generated Tool:**
+```json
+{
+  "name": "create_customer",
+  "description": "Create a new customer",
+  "inputSchema": {
+    "type": "object",
+    "properties": {
+      "email": { "type": "string" },
+      "name": { "type": "string" }
+    }
+  },
+  "source": "openapi"
+}
+```
+
+### From GraphQL
+
+Queries and mutations become tools:
+
+**Original GraphQL:**
+```graphql
+type Query {
+  user(id: ID!): User
+  users(limit: Int): [User!]!
+}
+
+type Mutation {
+  createUser(input: CreateUserInput!): User!
+}
+```
+
+**Generated Tools:**
+```json
+[
+  {
+    "name": "query_user",
+    "description": "Get a user by ID",
+    "inputSchema": {
+      "type": "object",
+      "properties": {
+        "id": { "type": "string" }
+      },
+      "required": ["id"]
+    },
+    "source": "graphql"
+  },
+  {
+    "name": "create_user",
+    "description": "Create a new user",
+    "inputSchema": {
+      "type": "object",
+      "properties": {
+        "input": {
+          "type": "object",
+          "properties": {
+            "name": { "type": "string" },
+            "email": { "type": "string" }
+          }
+        }
+      }
+    },
+    "source": "graphql"
+  }
+]
+```
+
+### From Python Code
+
+Functions with `@mcp.tool` decorators:
+
+**Original Python:**
+```python
+from mcp import tool
+
+@tool
+def analyze_text(text: str, language: str = "en") -> dict:
+    """Analyze the given text for sentiment and entities."""
+    # ...
+```
+
+**Generated Tool:**
+```json
+{
+  "name": "analyze_text",
+  "description": "Analyze the given text for sentiment and entities.",
+  "inputSchema": {
+    "type": "object",
+    "properties": {
+      "text": { "type": "string" },
+      "language": { "type": "string", "default": "en" }
+    },
+    "required": ["text"]
+  },
+  "source": "code"
+}
+```
+
+### From Existing MCP Servers
+
+For repos that are already MCP servers:
+
+```typescript
+// Original
+server.tool("calculate", "Perform calculations", {
+  expression: { type: "string" }
+}, async ({ expression }) => {
+  return eval(expression);
+});
+```
+
+**Extracted Tool:**
+```json
+{
+  "name": "calculate",
+  "description": "Perform calculations",
+  "inputSchema": {
+    "type": "object",
+    "properties": {
+      "expression": { "type": "string" }
+    }
+  },
+  "source": "mcp"
+}
+```
+
+---
+
+## Tool Naming
+
+Tools follow consistent naming conventions:
+
+| Source | Convention | Example |
+|--------|------------|---------|
+| Universal | `snake_case` | `read_file` |
+| OpenAPI | `operationId` or `method_path` | `create_customer` |
+| GraphQL | `type_field` | `query_user`, `mutation_create_user` |
+| Code | Original function name | `analyze_text` |
+
+### Conflict Resolution
+
+When multiple tools have the same name:
+
+1. Universal tools take precedence
+2. Later sources add numeric suffix: `read_file_2`
+3. Or use `--exclude-tools` to remove conflicts
+
+---
+
+## Tool Schemas
+
+All tools use JSON Schema for input validation:
+
+### Basic Types
+
+```json
+{
+  "type": "object",
+  "properties": {
+    "name": { "type": "string" },
+    "count": { "type": "integer" },
+    "enabled": { "type": "boolean" },
+    "score": { "type": "number" }
+  }
+}
+```
+
+### Arrays
+
+```json
+{
+  "type": "object",
+  "properties": {
+    "tags": {
+      "type": "array",
+      "items": { "type": "string" }
+    }
+  }
+}
+```
+
+### Nested Objects
+
+```json
+{
+  "type": "object",
+  "properties": {
+    "address": {
+      "type": "object",
+      "properties": {
+        "street": { "type": "string" },
+        "city": { "type": "string" }
+      }
+    }
+  }
+}
+```
+
+### Enums
+
+```json
+{
+  "type": "object",
+  "properties": {
+    "status": {
+      "type": "string",
+      "enum": ["pending", "active", "completed"]
+    }
+  }
+}
+```
+
+---
+
+## Filtering Tools
+
+### Include Specific Tools
+
+```bash
+github-to-mcp <url> --include-tools read_file,search_code,create_customer
+```
+
+### Exclude Tools
+
+```bash
+github-to-mcp <url> --exclude-tools get_readme
+```
+
+### Skip Universal Tools
+
+```bash
+github-to-mcp <url> --no-universal
+```
+
+---
+
+## See Also
+
+- [How It Works](how-it-works.md) - Extraction process
+- [Custom Tools](../guides/custom-tools.md) - Extending tools
+- [API Reference](../api/core.md) - Tool type definitions

package/mkdocs/docs/contributing/architecture.md

@@ -0,0 +1,262 @@
+# Architecture
+
+Technical architecture of GitHub to MCP.
+
+## Overview
+
+GitHub to MCP follows a monorepo architecture with clear separation of concerns:
+
+```
+┌─────────────────────────────────────────────────────────────────┐
+│                         Applications                             │
+│  ┌─────────────┐  ┌─────────────┐  ┌─────────────┐             │
+│  │   Web App   │  │    Docs     │  │   VS Code   │             │
+│  │  (Next.js)  │  │  (Nextra)   │  │ (Extension) │             │
+│  └──────┬──────┘  └─────────────┘  └──────┬──────┘             │
+│         │                                  │                     │
+│         └─────────────────┬────────────────┘                     │
+│                           ↓                                      │
+├─────────────────────────────────────────────────────────────────┤
+│                         Packages                                 │
+│  ┌─────────────────────────────────────────────────────────┐    │
+│  │                     @nirholas/github-to-mcp              │    │
+│  │  ┌───────────────┐  ┌───────────────┐  ┌─────────────┐  │    │
+│  │  │   Generator   │  │  Extractors   │  │   GitHub    │  │    │
+│  │  │               │  │               │  │   Client    │  │    │
+│  │  └───────┬───────┘  └───────┬───────┘  └──────┬──────┘  │    │
+│  └──────────┼──────────────────┼─────────────────┼─────────┘    │
+│             │                  │                 │               │
+│  ┌──────────┴──────────┐ ┌────┴────────────────┴─────────┐     │
+│  │  @github-to-mcp/    │ │   @github-to-mcp/mcp-server   │     │
+│  │  openapi-parser     │ │                               │     │
+│  └─────────────────────┘ └───────────────────────────────┘     │
+└─────────────────────────────────────────────────────────────────┘
+```
+
+## Package Responsibilities
+
+### @nirholas/github-to-mcp (core)
+
+The main library that orchestrates the conversion process.
+
+**Responsibilities:**
+- Public API (`generateFromGithub`, `parseRepository`)
+- Repository classification
+- Tool extraction coordination
+- Code generation
+- Output bundling
+
+**Key Components:**
+
+```typescript
+// Generator - Main orchestrator
+class GithubToMcpGenerator {
+  async generate(url: string, options: Options): Promise<Result>
+}
+
+// GitHub Client - API interaction
+class GithubClient {
+  async getRepository(url: string): Promise<RepoInfo>
+  async getFileTree(url: string): Promise<FileTree>
+  async getFile(url: string, path: string): Promise<string>
+}
+
+// Classifier - Repository type detection
+function classifyRepository(info: RepoInfo): RepositoryType
+
+// Extractors - Tool extraction
+interface Extractor {
+  extract(info: RepoInfo): Promise<Tool[]>
+}
+```
+
+### @github-to-mcp/openapi-parser
+
+Parses API specifications into tool definitions.
+
+**Responsibilities:**
+- OpenAPI 2.0/3.0/3.1 parsing
+- GraphQL schema parsing
+- JSON Schema generation
+- Spec file detection
+
+**Key Components:**
+
+```typescript
+// OpenAPI Parser
+function parseOpenAPI(spec: string | object): Promise<Tool[]>
+
+// GraphQL Parser
+function parseGraphQL(schema: string): Promise<Tool[]>
+
+// Spec Finder
+function findSpecs(files: FileTree): SpecFiles
+```
+
+### @github-to-mcp/mcp-server
+
+MCP server implementation for generated servers.
+
+**Responsibilities:**
+- MCP protocol implementation
+- Tool registration and execution
+- Transport handling (stdio, HTTP)
+- Error handling
+
+**Key Components:**
+
+```typescript
+// MCP Server
+class McpServer {
+  addTool(tool: ToolDefinition): void
+  start(): Promise<void>
+  stop(): Promise<void>
+}
+
+// Transports
+class StdioTransport implements Transport {}
+class HttpTransport implements Transport {}
+```
+
+## Data Flow
+
+### Generation Flow
+
+```
+1. User Input (GitHub URL)
+           ↓
+2. GithubClient.getRepository()
+   - Fetch metadata
+   - Fetch README
+   - Fetch file tree
+           ↓
+3. classifyRepository()
+   - Analyze patterns
+   - Determine type
+           ↓
+4. Extractors.extract()
+   - Universal tools
+   - OpenAPI extraction
+   - GraphQL extraction
+   - Code analysis
+           ↓
+5. CodeGenerator.generate()
+   - Apply templates
+   - Generate implementations
+           ↓
+6. Bundler.bundle()
+   - Create package.json
+   - Organize files
+   - Write to disk
+```
+
+### Tool Execution Flow
+
+```
+1. AI Client sends tools/call
+           ↓
+2. McpServer receives request
+   - Parse JSON-RPC
+   - Validate parameters
+           ↓
+3. Tool.execute()
+   - Run implementation
+   - Handle errors
+           ↓
+4. Format response
+   - Create content array
+   - Return result
+```
+
+## File Organization
+
+### Core Package Structure
+
+```
+packages/core/
+├── src/
+│   ├── index.ts           # Public exports
+│   ├── generator.ts       # Main generator class
+│   ├── types.ts           # TypeScript types
+│   ├── github/
+│   │   ├── client.ts      # GitHub API client
+│   │   ├── cache.ts       # Request caching
+│   │   └── types.ts       # GitHub types
+│   ├── classification/
+│   │   ├── classifier.ts  # Repository classifier
+│   │   └── patterns.ts    # Detection patterns
+│   ├── extractors/
+│   │   ├── universal.ts   # Universal tools
+│   │   ├── openapi.ts     # OpenAPI extractor
+│   │   ├── graphql.ts     # GraphQL extractor
+│   │   └── code.ts        # Code analysis
+│   ├── generators/
+│   │   ├── typescript.ts  # TS code generator
+│   │   └── python.ts      # Python code generator
+│   └── utils/
+│       ├── schema.ts      # JSON Schema helpers
+│       └── naming.ts      # Naming conventions
+├── tests/
+├── package.json
+└── tsconfig.json
+```
+
+### Web App Structure
+
+```
+apps/web/
+├── app/
+│   ├── layout.tsx         # Root layout
+│   ├── page.tsx           # Home page
+│   ├── api/
+│   │   └── generate/      # API routes
+│   ├── playground/        # Playground page
+│   └── batch/             # Batch conversion
+├── components/
+│   ├── Header.tsx
+│   ├── Footer.tsx
+│   ├── GeneratorForm.tsx
+│   └── ...
+├── lib/
+│   ├── generator.ts       # Client-side generator
+│   └── utils.ts
+└── public/
+```
+
+## Design Decisions
+
+### Why Monorepo?
+
+- **Shared code**: Common utilities across packages
+- **Atomic changes**: Related changes in one PR
+- **Consistent tooling**: Same lint, test, build config
+- **Easy local development**: Automatic linking
+
+### Why TypeScript?
+
+- **Type safety**: Catch errors at compile time
+- **Better DX**: IDE autocomplete and documentation
+- **Self-documenting**: Types serve as documentation
+- **Industry standard**: Common in JS/TS ecosystem
+
+### Why Next.js for Web?
+
+- **Server components**: Fast initial load
+- **API routes**: Built-in backend
+- **Vercel deployment**: Zero-config hosting
+- **React ecosystem**: Rich component libraries
+
+### Why Separate Parser Package?
+
+- **Reusability**: Can be used independently
+- **Testability**: Easier to test in isolation
+- **Performance**: Tree-shakeable for size
+- **Maintenance**: Clear boundaries
+
+---
+
+## See Also
+
+- [Development Setup](development.md) - Get started contributing
+- [Testing](testing.md) - Write and run tests
+- [How It Works](../concepts/how-it-works.md) - User-facing explanation