github-to-mcp-monorepo 1.0.0

package/mkdocs/docs/contributing/development.md

@@ -0,0 +1,245 @@
+# Development Setup
+
+Set up your local development environment for contributing to GitHub to MCP.
+
+## Prerequisites
+
+- **Node.js 18+** - [Download](https://nodejs.org)
+- **pnpm** - [Install](https://pnpm.io/installation)
+- **Git** - [Download](https://git-scm.com)
+
+## Clone and Install
+
+```bash
+# Clone the repository
+git clone https://github.com/nirholas/github-to-mcp
+cd github-to-mcp
+
+# Install dependencies
+pnpm install
+```
+
+## Project Structure
+
+```
+github-to-mcp/
+├── apps/
+│   ├── web/            # Next.js web application
+│   ├── docs/           # Documentation (Nextra)
+│   └── vscode/         # VS Code extension
+├── packages/
+│   ├── core/           # Core conversion library
+│   ├── openapi-parser/ # OpenAPI/GraphQL parser
+│   └── mcp-server/     # MCP server implementation
+├── mkdocs/             # MkDocs documentation
+├── tests/              # Integration tests
+└── templates/          # Code generation templates
+```
+
+## Development Commands
+
+### Build All Packages
+
+```bash
+pnpm build
+```
+
+### Build Specific Package
+
+```bash
+pnpm --filter @nirholas/github-to-mcp build
+pnpm --filter @github-to-mcp/openapi-parser build
+```
+
+### Run Development Server
+
+```bash
+pnpm dev
+# Opens web app at http://localhost:3000
+```
+
+### Run Tests
+
+```bash
+# All tests
+pnpm test
+
+# Watch mode
+pnpm test:watch
+
+# Coverage
+pnpm test:coverage
+```
+
+### Lint and Format
+
+```bash
+# Check
+pnpm lint
+
+# Fix
+pnpm lint:fix
+
+# Format
+pnpm format
+```
+
+## Package Development
+
+### Core Package
+
+The main conversion library:
+
+```bash
+cd packages/core
+pnpm build
+pnpm test
+```
+
+Key files:
+- `src/index.ts` - Public API
+- `src/generator.ts` - Main generator
+- `src/extractors/` - Tool extraction
+- `src/github/` - GitHub API client
+
+### OpenAPI Parser
+
+Parse OpenAPI and GraphQL specs:
+
+```bash
+cd packages/openapi-parser
+pnpm build
+pnpm test
+```
+
+Key files:
+- `src/openapi.ts` - OpenAPI parser
+- `src/graphql.ts` - GraphQL parser
+- `src/utils.ts` - Shared utilities
+
+### MCP Server
+
+MCP server implementation:
+
+```bash
+cd packages/mcp-server
+pnpm build
+pnpm test
+```
+
+Key files:
+- `src/server.ts` - Server class
+- `src/transport/` - Transport implementations
+- `src/tools/` - Tool registration
+
+## Web App Development
+
+```bash
+cd apps/web
+pnpm dev
+# http://localhost:3000
+```
+
+Key directories:
+- `app/` - Next.js app router pages
+- `components/` - React components
+- `lib/` - Utilities and helpers
+
+## Environment Setup
+
+Create `.env.local` in the root:
+
+```bash
+# Optional: For testing with private repos
+GITHUB_TOKEN=ghp_xxxxx
+
+# Optional: For enhanced extraction
+OPENAI_API_KEY=sk-xxxxx
+```
+
+## IDE Setup
+
+### VS Code
+
+Install recommended extensions:
+- ESLint
+- Prettier
+- TypeScript
+
+The project includes `.vscode/settings.json` for automatic formatting.
+
+### Debugging
+
+Launch configurations are provided in `.vscode/launch.json`:
+
+1. Open VS Code
+2. Go to Run and Debug (Cmd+Shift+D)
+3. Select a configuration
+4. Press F5
+
+## Common Tasks
+
+### Add a New Dependency
+
+```bash
+# Root workspace
+pnpm add -w <package>
+
+# Specific package
+pnpm --filter @nirholas/github-to-mcp add <package>
+```
+
+### Create a Changeset
+
+For version management:
+
+```bash
+pnpm changeset
+```
+
+### Link Local Packages
+
+For testing locally:
+
+```bash
+pnpm link --global
+```
+
+## Troubleshooting
+
+### Build Errors
+
+```bash
+# Clean and rebuild
+pnpm clean
+pnpm install
+pnpm build
+```
+
+### Test Failures
+
+```bash
+# Run specific test
+pnpm test -- --grep "pattern"
+
+# Update snapshots
+pnpm test -- -u
+```
+
+### Type Errors
+
+```bash
+# Check types
+pnpm typecheck
+
+# Generate types
+pnpm build
+```
+
+---
+
+## Next Steps
+
+- [Architecture](architecture.md) - Understand the codebase
+- [Testing](testing.md) - Write tests
+- [Contributing Guide](index.md) - Contribution guidelines

package/mkdocs/docs/contributing/index.md

@@ -0,0 +1,73 @@
+# Contributing
+
+Thank you for your interest in contributing to GitHub to MCP! 🎉
+
+## Quick Start
+
+```bash
+# Clone the repository
+git clone https://github.com/nirholas/github-to-mcp
+cd github-to-mcp
+
+# Install dependencies
+pnpm install
+
+# Build all packages
+pnpm build
+
+# Run tests
+pnpm test
+
+# Start development server
+pnpm dev
+```
+
+## Ways to Contribute
+
+<div class="feature-grid" markdown>
+
+<div class="feature-card" markdown>
+
+### 🐛 Bug Reports
+Found a bug? [Open an issue](https://github.com/nirholas/github-to-mcp/issues/new?template=bug_report.md) with steps to reproduce.
+
+</div>
+
+<div class="feature-card" markdown>
+
+### 💡 Feature Requests
+Have an idea? [Start a discussion](https://github.com/nirholas/github-to-mcp/discussions/new?category=ideas).
+
+</div>
+
+<div class="feature-card" markdown>
+
+### 📖 Documentation
+Improve docs, fix typos, add examples.
+
+</div>
+
+<div class="feature-card" markdown>
+
+### 🔧 Code
+Fix bugs, add features, improve performance.
+
+</div>
+
+</div>
+
+## Guides
+
+| Guide | Description |
+|-------|-------------|
+| [Development Setup](development.md) | Set up your local environment |
+| [Architecture](architecture.md) | Understand the codebase |
+| [Testing](testing.md) | Write and run tests |
+
+## Code of Conduct
+
+Be respectful and inclusive. See our [Code of Conduct](https://github.com/nirholas/github-to-mcp/blob/main/CODE_OF_CONDUCT.md).
+
+## License
+
+By contributing, you agree that your contributions will be licensed under the MIT License.

package/mkdocs/docs/contributing/testing.md

@@ -0,0 +1,320 @@
+# Testing
+
+Guide to writing and running tests for GitHub to MCP.
+
+## Running Tests
+
+### All Tests
+
+```bash
+pnpm test
+```
+
+### Watch Mode
+
+```bash
+pnpm test:watch
+```
+
+### Coverage Report
+
+```bash
+pnpm test:coverage
+```
+
+### Specific Package
+
+```bash
+pnpm --filter @nirholas/github-to-mcp test
+pnpm --filter @github-to-mcp/openapi-parser test
+```
+
+## Test Structure
+
+```
+tests/
+├── unit/                    # Unit tests
+│   ├── core/
+│   │   ├── generator.test.ts
+│   │   ├── classifier.test.ts
+│   │   └── extractors/
+│   ├── openapi-parser/
+│   └── mcp-server/
+├── integration/             # Integration tests
+│   ├── generation.test.ts
+│   └── end-to-end.test.ts
+└── fixtures/                # Test data
+    ├── repos/
+    ├── openapi/
+    └── graphql/
+```
+
+## Writing Tests
+
+### Unit Tests
+
+Test individual functions in isolation:
+
+```typescript
+import { describe, it, expect, vi } from 'vitest';
+import { classifyRepository } from '@nirholas/github-to-mcp';
+
+describe('classifyRepository', () => {
+  it('should classify MCP server repos', () => {
+    const repo = {
+      packageJson: {
+        dependencies: {
+          '@modelcontextprotocol/sdk': '^1.0.0'
+        }
+      }
+    };
+    
+    expect(classifyRepository(repo)).toBe('mcp-server');
+  });
+  
+  it('should classify API SDK repos', () => {
+    const repo = {
+      files: ['openapi.json'],
+      packageJson: {}
+    };
+    
+    expect(classifyRepository(repo)).toBe('api-sdk');
+  });
+});
+```
+
+### Mocking
+
+Use Vitest's mocking capabilities:
+
+```typescript
+import { vi } from 'vitest';
+import { GithubClient } from '../src/github/client';
+
+// Mock entire module
+vi.mock('../src/github/client');
+
+// Mock specific function
+const mockFetch = vi.fn();
+vi.spyOn(global, 'fetch').mockImplementation(mockFetch);
+
+// Setup mock return value
+mockFetch.mockResolvedValue({
+  ok: true,
+  json: () => Promise.resolve({ data: 'test' })
+});
+```
+
+### Integration Tests
+
+Test multiple components together:
+
+```typescript
+import { describe, it, expect, beforeAll, afterAll } from 'vitest';
+import { generateFromGithub } from '@nirholas/github-to-mcp';
+
+describe('End-to-end generation', () => {
+  it('should generate MCP server from public repo', async () => {
+    const result = await generateFromGithub(
+      'https://github.com/octocat/Hello-World',
+      { token: process.env.GITHUB_TOKEN }
+    );
+    
+    expect(result.tools).toHaveLength(4); // Universal tools
+    expect(result.tools.map(t => t.name)).toContain('read_file');
+    expect(result.tools.map(t => t.name)).toContain('list_files');
+  });
+  
+  it('should extract OpenAPI tools', async () => {
+    const result = await generateFromGithub(
+      'https://github.com/stripe/stripe-node'
+    );
+    
+    // Should have more than universal tools
+    expect(result.tools.length).toBeGreaterThan(4);
+    expect(result.tools.some(t => t.source === 'openapi')).toBe(true);
+  });
+});
+```
+
+### Fixture Tests
+
+Test with predefined data:
+
+```typescript
+import { readFixture } from '../helpers';
+import { parseOpenAPI } from '@github-to-mcp/openapi-parser';
+
+describe('OpenAPI Parser', () => {
+  it('should parse petstore spec', async () => {
+    const spec = await readFixture('openapi/petstore.json');
+    const tools = await parseOpenAPI(spec);
+    
+    expect(tools).toMatchSnapshot();
+  });
+  
+  it('should parse GitHub API spec', async () => {
+    const spec = await readFixture('openapi/github-api.yaml');
+    const tools = await parseOpenAPI(spec);
+    
+    expect(tools.length).toBeGreaterThan(100);
+  });
+});
+```
+
+## Test Helpers
+
+### fixtures/helpers.ts
+
+```typescript
+import fs from 'fs/promises';
+import path from 'path';
+
+export async function readFixture(name: string): Promise<string> {
+  const fixturePath = path.join(__dirname, 'fixtures', name);
+  return fs.readFile(fixturePath, 'utf-8');
+}
+
+export function createMockRepo(overrides = {}) {
+  return {
+    owner: 'test',
+    name: 'repo',
+    url: 'https://github.com/test/repo',
+    readme: '# Test Repo',
+    files: [],
+    packageJson: {},
+    ...overrides
+  };
+}
+
+export function createMockTool(overrides = {}) {
+  return {
+    name: 'test_tool',
+    description: 'A test tool',
+    inputSchema: { type: 'object' },
+    source: 'universal',
+    ...overrides
+  };
+}
+```
+
+## Testing Patterns
+
+### Testing Extractors
+
+```typescript
+describe('OpenAPI Extractor', () => {
+  it('should extract operations with operationId', async () => {
+    const repo = createMockRepo({
+      files: ['openapi.json'],
+      fileContents: {
+        'openapi.json': JSON.stringify({
+          openapi: '3.0.0',
+          paths: {
+            '/users': {
+              get: {
+                operationId: 'listUsers',
+                summary: 'List all users'
+              }
+            }
+          }
+        })
+      }
+    });
+    
+    const extractor = new OpenAPIExtractor();
+    const tools = await extractor.extract(repo);
+    
+    expect(tools).toHaveLength(1);
+    expect(tools[0].name).toBe('listUsers');
+  });
+});
+```
+
+### Testing Generators
+
+```typescript
+describe('TypeScript Generator', () => {
+  it('should generate valid TypeScript', async () => {
+    const tools = [createMockTool({ name: 'read_file' })];
+    const generator = new TypeScriptGenerator();
+    
+    const code = generator.generate(tools);
+    
+    // Check it's valid TypeScript by parsing
+    expect(() => typescript.createSourceFile(
+      'test.ts',
+      code,
+      typescript.ScriptTarget.Latest
+    )).not.toThrow();
+  });
+});
+```
+
+### Testing Error Handling
+
+```typescript
+describe('Error handling', () => {
+  it('should throw on invalid URL', async () => {
+    await expect(
+      generateFromGithub('not-a-url')
+    ).rejects.toThrow('Invalid GitHub URL');
+  });
+  
+  it('should throw on rate limit', async () => {
+    vi.mocked(fetch).mockResolvedValueOnce({
+      ok: false,
+      status: 403,
+      headers: new Headers({
+        'X-RateLimit-Remaining': '0'
+      })
+    });
+    
+    await expect(
+      generateFromGithub('https://github.com/test/repo')
+    ).rejects.toThrow('Rate limit exceeded');
+  });
+});
+```
+
+## Snapshot Testing
+
+For complex outputs, use snapshots:
+
+```typescript
+it('should generate expected server code', async () => {
+  const result = await generateFromGithub(
+    'https://github.com/test/simple-repo'
+  );
+  
+  expect(result.toTypeScript()).toMatchSnapshot();
+});
+```
+
+Update snapshots when behavior changes intentionally:
+
+```bash
+pnpm test -- -u
+```
+
+## Coverage Goals
+
+| Package | Target |
+|---------|--------|
+| Core | 80%+ |
+| OpenAPI Parser | 90%+ |
+| MCP Server | 85%+ |
+
+Check coverage:
+
+```bash
+pnpm test:coverage
+```
+
+---
+
+## See Also
+
+- [Development Setup](development.md) - Setup environment
+- [Architecture](architecture.md) - Code structure
+- [Contributing](index.md) - Contribution guidelines