github-to-mcp-monorepo 1.0.0

package/mkdocs/docs/api/core.md

@@ -0,0 +1,318 @@
+# Core API
+
+The `@nirholas/github-to-mcp` package provides the core conversion functionality.
+
+## Installation
+
+```bash
+npm install @nirholas/github-to-mcp
+```
+
+## Functions
+
+### generateFromGithub
+
+Generate an MCP server from a GitHub repository URL.
+
+```typescript
+function generateFromGithub(
+  url: string,
+  options?: GeneratorOptions
+): Promise<GeneratorResult>
+```
+
+#### Parameters
+
+| Parameter | Type | Description |
+|-----------|------|-------------|
+| `url` | `string` | GitHub repository URL |
+| `options` | `GeneratorOptions` | Optional configuration |
+
+#### Returns
+
+`Promise<GeneratorResult>` - The generation result with tools and save methods.
+
+#### Example
+
+```typescript
+import { generateFromGithub } from '@nirholas/github-to-mcp';
+
+const result = await generateFromGithub(
+  'https://github.com/stripe/stripe-node',
+  {
+    token: process.env.GITHUB_TOKEN,
+    language: 'typescript',
+    includeUniversalTools: true,
+  }
+);
+
+console.log(`Generated ${result.tools.length} tools`);
+await result.save('./stripe-mcp');
+```
+
+---
+
+### parseRepository
+
+Parse a repository and extract tool information without generating code.
+
+```typescript
+function parseRepository(
+  url: string,
+  options?: ParseOptions
+): Promise<RepositoryInfo>
+```
+
+#### Parameters
+
+| Parameter | Type | Description |
+|-----------|------|-------------|
+| `url` | `string` | GitHub repository URL |
+| `options` | `ParseOptions` | Optional configuration |
+
+#### Returns
+
+`Promise<RepositoryInfo>` - Parsed repository information.
+
+#### Example
+
+```typescript
+import { parseRepository } from '@nirholas/github-to-mcp';
+
+const info = await parseRepository('https://github.com/openai/openai-node');
+
+console.log(`Type: ${info.type}`);           // 'api-sdk'
+console.log(`Language: ${info.language}`);   // 'TypeScript'
+console.log(`Tools found: ${info.tools.length}`);
+```
+
+---
+
+### classifyRepository
+
+Classify a repository by analyzing its contents.
+
+```typescript
+function classifyRepository(
+  repoInfo: RepositoryInfo
+): RepositoryType
+```
+
+#### Returns
+
+One of: `'mcp-server'` | `'api-sdk'` | `'cli-tool'` | `'library'` | `'documentation'` | `'data'` | `'unknown'`
+
+---
+
+### extractTools
+
+Extract tools from various sources in a repository.
+
+```typescript
+function extractTools(
+  repoInfo: RepositoryInfo,
+  options?: ExtractionOptions
+): Promise<Tool[]>
+```
+
+#### Example
+
+```typescript
+import { parseRepository, extractTools } from '@nirholas/github-to-mcp';
+
+const info = await parseRepository('https://github.com/owner/repo');
+const tools = await extractTools(info, {
+  fromOpenAPI: true,
+  fromGraphQL: true,
+  fromCode: true,
+});
+
+console.log(`Extracted ${tools.length} tools`);
+```
+
+---
+
+## Types
+
+### GeneratorOptions
+
+```typescript
+interface GeneratorOptions {
+  /** GitHub personal access token */
+  token?: string;
+  
+  /** Output language */
+  language?: 'typescript' | 'python';
+  
+  /** Only include these tools */
+  includeTools?: string[];
+  
+  /** Exclude these tools */
+  excludeTools?: string[];
+  
+  /** Include universal tools (read_file, etc.) */
+  includeUniversalTools?: boolean;
+  
+  /** Extract tools from OpenAPI specs */
+  extractFromOpenAPI?: boolean;
+  
+  /** Extract tools from GraphQL schemas */
+  extractFromGraphQL?: boolean;
+  
+  /** Extract tools from source code */
+  extractFromCode?: boolean;
+  
+  /** Extract tools from README */
+  extractFromReadme?: boolean;
+  
+  /** Maximum directory depth to scan */
+  maxDepth?: number;
+  
+  /** Maximum file size to read (bytes) */
+  maxFileSize?: number;
+  
+  /** Request timeout (ms) */
+  timeout?: number;
+}
+```
+
+### GeneratorResult
+
+```typescript
+interface GeneratorResult {
+  /** List of generated tools */
+  tools: Tool[];
+  
+  /** Repository metadata */
+  metadata: RepositoryMetadata;
+  
+  /** Repository classification */
+  type: RepositoryType;
+  
+  /** Save to a directory */
+  save(path: string): Promise<void>;
+  
+  /** Get TypeScript code */
+  toTypeScript(): string;
+  
+  /** Get Python code */
+  toPython(): string;
+  
+  /** Get as zip buffer */
+  toZip(): Promise<Buffer>;
+}
+```
+
+### Tool
+
+```typescript
+interface Tool {
+  /** Tool name (snake_case) */
+  name: string;
+  
+  /** Human-readable description */
+  description: string;
+  
+  /** JSON Schema for input parameters */
+  inputSchema: JSONSchema;
+  
+  /** Where the tool was extracted from */
+  source: 'universal' | 'openapi' | 'graphql' | 'code' | 'readme';
+  
+  /** Tool implementation (generated code) */
+  implementation?: string;
+}
+```
+
+### RepositoryInfo
+
+```typescript
+interface RepositoryInfo {
+  /** Repository owner */
+  owner: string;
+  
+  /** Repository name */
+  name: string;
+  
+  /** Full URL */
+  url: string;
+  
+  /** Default branch */
+  defaultBranch: string;
+  
+  /** Repository description */
+  description: string;
+  
+  /** Star count */
+  stars: number;
+  
+  /** Primary language */
+  language: string;
+  
+  /** Repository classification */
+  type: RepositoryType;
+  
+  /** README content */
+  readme: string;
+  
+  /** File tree */
+  files: FileTree;
+}
+```
+
+### RepositoryType
+
+```typescript
+type RepositoryType = 
+  | 'mcp-server'      // Existing MCP server
+  | 'api-sdk'         // API client library
+  | 'cli-tool'        // Command-line tool
+  | 'library'         // General library
+  | 'documentation'   // Documentation only
+  | 'data'            // Data/config repo
+  | 'unknown';        // Unclassified
+```
+
+---
+
+## Error Handling
+
+### GithubApiError
+
+Thrown when GitHub API requests fail.
+
+```typescript
+import { generateFromGithub, GithubApiError } from '@nirholas/github-to-mcp';
+
+try {
+  await generateFromGithub('https://github.com/owner/private-repo');
+} catch (error) {
+  if (error instanceof GithubApiError) {
+    console.log(`GitHub API error: ${error.status} - ${error.message}`);
+  }
+}
+```
+
+### ExtractionError
+
+Thrown when tool extraction fails.
+
+```typescript
+import { ExtractionError } from '@nirholas/github-to-mcp';
+
+try {
+  // ...
+} catch (error) {
+  if (error instanceof ExtractionError) {
+    console.log(`Extraction failed: ${error.source} - ${error.message}`);
+  }
+}
+```
+
+---
+
+## See Also
+
+- [OpenAPI Parser](openapi-parser.md) - Parser module
+- [MCP Server](mcp-server.md) - Server implementation
+- [Configuration](../getting-started/configuration.md) - Options guide

package/mkdocs/docs/api/index.md

@@ -0,0 +1,128 @@
+# API Reference
+
+Programmatic API for GitHub to MCP.
+
+## Installation
+
+```bash
+npm install @nirholas/github-to-mcp
+```
+
+## Packages
+
+| Package | Description |
+|---------|-------------|
+| [`@nirholas/github-to-mcp`](core.md) | Core conversion library |
+| [`@github-to-mcp/openapi-parser`](openapi-parser.md) | OpenAPI/GraphQL parser |
+| [`@github-to-mcp/mcp-server`](mcp-server.md) | MCP server implementation |
+
+## Quick Start
+
+```typescript
+import { generateFromGithub } from '@nirholas/github-to-mcp';
+
+// Generate from a GitHub URL
+const result = await generateFromGithub('https://github.com/stripe/stripe-node');
+
+// Access generated tools
+console.log(`Generated ${result.tools.length} tools`);
+result.tools.forEach(tool => {
+  console.log(`- ${tool.name}: ${tool.description}`);
+});
+
+// Save to disk
+await result.save('./my-mcp-server');
+
+// Or get the code directly
+const code = result.toTypeScript();
+```
+
+## Core Functions
+
+### generateFromGithub
+
+Main function to generate MCP server from a repository.
+
+```typescript
+import { generateFromGithub, type GeneratorOptions } from '@nirholas/github-to-mcp';
+
+const options: GeneratorOptions = {
+  token: process.env.GITHUB_TOKEN,
+  language: 'typescript',
+  includeUniversalTools: true,
+};
+
+const result = await generateFromGithub(
+  'https://github.com/owner/repo',
+  options
+);
+```
+
+### parseRepository
+
+Parse a repository without generating code.
+
+```typescript
+import { parseRepository } from '@nirholas/github-to-mcp';
+
+const info = await parseRepository('https://github.com/owner/repo');
+console.log(info.type);        // 'api-sdk' | 'mcp-server' | etc.
+console.log(info.tools);       // Extracted tool definitions
+console.log(info.metadata);    // Repo metadata
+```
+
+### createMcpServer
+
+Create an MCP server instance from tools.
+
+```typescript
+import { createMcpServer } from '@nirholas/github-to-mcp';
+
+const server = createMcpServer({
+  name: 'my-server',
+  tools: [...],
+  transport: 'stdio',  // or 'http'
+});
+
+await server.start();
+```
+
+## Type Definitions
+
+```typescript
+interface GeneratorOptions {
+  token?: string;
+  language?: 'typescript' | 'python';
+  includeTools?: string[];
+  excludeTools?: string[];
+  includeUniversalTools?: boolean;
+  extractFromOpenAPI?: boolean;
+  extractFromGraphQL?: boolean;
+  extractFromCode?: boolean;
+  extractFromReadme?: boolean;
+  maxDepth?: number;
+  maxFileSize?: number;
+  timeout?: number;
+}
+
+interface GeneratorResult {
+  tools: Tool[];
+  metadata: RepositoryMetadata;
+  save(path: string): Promise<void>;
+  toTypeScript(): string;
+  toPython(): string;
+}
+
+interface Tool {
+  name: string;
+  description: string;
+  inputSchema: JSONSchema;
+  source: 'universal' | 'openapi' | 'graphql' | 'code' | 'readme';
+}
+```
+
+## See Also
+
+- [Core API](core.md) - Full core library reference
+- [OpenAPI Parser](openapi-parser.md) - Parser module
+- [Configuration](../getting-started/configuration.md) - Options reference