github-to-mcp-monorepo 1.0.0

package/mkdocs/docs/guides/cursor.md

@@ -0,0 +1,188 @@
+# Cursor Integration
+
+Use GitHub to MCP with Cursor IDE for AI-assisted coding with full codebase context.
+
+## Prerequisites
+
+- [Cursor](https://cursor.sh) installed
+- A generated MCP server (see [Quick Start](../getting-started/quickstart.md))
+- Node.js 18+ installed
+
+## Step 1: Generate Your MCP Server
+
+```bash
+npx @nirholas/github-to-mcp https://github.com/owner/repo -o ~/mcp-servers/my-repo
+```
+
+## Step 2: Configure Cursor
+
+Cursor's MCP configuration is in your settings. Open Cursor and:
+
+1. Press `Cmd/Ctrl + ,` to open Settings
+2. Search for "MCP"
+3. Click "Edit in settings.json"
+
+Or edit directly:
+
+=== "macOS"
+
+    ```
+    ~/Library/Application Support/Cursor/User/settings.json
+    ```
+
+=== "Windows"
+
+    ```
+    %APPDATA%\Cursor\User\settings.json
+    ```
+
+=== "Linux"
+
+    ```
+    ~/.config/Cursor/User/settings.json
+    ```
+
+## Step 3: Add MCP Server
+
+Add your MCP server configuration:
+
+```json
+{
+  "mcp.servers": {
+    "my-repo": {
+      "command": "node",
+      "args": ["/Users/yourname/mcp-servers/my-repo/server.mjs"]
+    }
+  }
+}
+```
+
+## Step 4: Restart Cursor
+
+1. Close all Cursor windows
+2. Relaunch Cursor
+3. The MCP tools should now be available
+
+## Using MCP with Cursor
+
+### In Chat (Cmd+L)
+
+Ask questions about the connected repository:
+
+> **You:** How does the authentication middleware work?
+>
+> **Cursor:** *Uses MCP tools to search and read files* The authentication middleware in this repo...
+
+### In Composer (Cmd+K)
+
+Reference MCP tools when generating code:
+
+> **You:** Create a new endpoint similar to the existing /users endpoint
+>
+> **Cursor:** *Uses `search_code` to find the users endpoint, `read_file` to understand the pattern*
+
+### Context Awareness
+
+With MCP connected, Cursor can:
+
+- Search the entire repository for relevant code
+- Understand API patterns and conventions
+- Find related implementations
+- Reference documentation
+
+## Multiple Repositories
+
+Configure multiple repos for cross-codebase AI assistance:
+
+```json
+{
+  "mcp.servers": {
+    "frontend": {
+      "command": "node",
+      "args": ["/path/to/frontend-mcp/server.mjs"]
+    },
+    "backend": {
+      "command": "node",
+      "args": ["/path/to/backend-mcp/server.mjs"]
+    },
+    "shared-lib": {
+      "command": "node",
+      "args": ["/path/to/shared-mcp/server.mjs"]
+    }
+  }
+}
+```
+
+## Workflow Tips
+
+### 1. Connect External Dependencies
+
+Generate MCP servers for libraries you use:
+
+```bash
+# Your project's main dependency
+npx @nirholas/github-to-mcp https://github.com/prisma/prisma -o ~/mcp-servers/prisma
+```
+
+Then ask Cursor about Prisma patterns while coding.
+
+### 2. Reference Documentation Repos
+
+```bash
+npx @nirholas/github-to-mcp https://github.com/vercel/next.js -o ~/mcp-servers/nextjs
+```
+
+Ask about Next.js best practices with real code context.
+
+### 3. Keep Servers Updated
+
+When dependencies update, regenerate:
+
+```bash
+npx @nirholas/github-to-mcp https://github.com/prisma/prisma -o ~/mcp-servers/prisma --force
+```
+
+## Troubleshooting
+
+### MCP Not Working
+
+1. Check Cursor version (MCP requires recent versions)
+2. Verify the config file location
+3. Test the server standalone:
+   ```bash
+   node ~/mcp-servers/my-repo/server.mjs
+   ```
+
+### Slow Responses
+
+For large repos, optimize your MCP server:
+
+```bash
+npx @nirholas/github-to-mcp <url> \
+  --exclude-tools get_readme \
+  -o ~/mcp-servers/my-repo
+```
+
+### Permission Errors
+
+On macOS, you may need to allow Node.js:
+
+1. System Preferences → Security & Privacy
+2. Allow `node` to run
+
+---
+
+## Best Practices
+
+1. **Local repos first** - For your active project, use Cursor's built-in context
+2. **MCP for external** - Use MCP for dependencies and reference repos
+3. **Selective tools** - Exclude unused tools for faster responses
+4. **Keep servers lean** - Don't generate servers for massive repos unless needed
+
+---
+
+## Next Steps
+
+- [VS Code Integration](vscode.md)
+- [Custom Tools](custom-tools.md)
+- [Batch Conversion](batch.md) - Generate multiple servers at once

package/mkdocs/docs/guides/custom-tools.md

@@ -0,0 +1,367 @@
+# Custom Tools
+
+Extend and customize the generated MCP tools to fit your needs.
+
+## Understanding Generated Tools
+
+Each generated MCP server includes tool implementations that you can modify:
+
+```
+my-mcp-server/
+├── server.mjs        # Main server (registers tools)
+├── tools/
+│   ├── index.mjs     # Tool exports
+│   ├── read_file.mjs
+│   ├── list_files.mjs
+│   ├── search_code.mjs
+│   └── get_readme.mjs
+└── package.json
+```
+
+## Modifying Existing Tools
+
+### Example: Add Caching to read_file
+
+Edit `tools/read_file.mjs`:
+
+```javascript
+import { LRUCache } from 'lru-cache';
+
+// Add a cache
+const cache = new LRUCache({ max: 100, ttl: 1000 * 60 * 5 });
+
+export const readFileTool = {
+  name: 'read_file',
+  description: 'Read the contents of a file from the repository',
+  inputSchema: {
+    type: 'object',
+    properties: {
+      path: {
+        type: 'string',
+        description: 'Path to the file to read'
+      }
+    },
+    required: ['path']
+  },
+  async execute({ path }) {
+    // Check cache first
+    const cached = cache.get(path);
+    if (cached) {
+      return { content: cached, cached: true };
+    }
+    
+    // Fetch if not cached
+    const content = await fetchFileFromGithub(path);
+    cache.set(path, content);
+    
+    return { content, cached: false };
+  }
+};
+```
+
+### Example: Add Filtering to list_files
+
+```javascript
+export const listFilesTool = {
+  name: 'list_files',
+  description: 'List files in a directory with optional filtering',
+  inputSchema: {
+    type: 'object',
+    properties: {
+      path: {
+        type: 'string',
+        description: 'Directory path'
+      },
+      pattern: {
+        type: 'string',
+        description: 'Glob pattern to filter files (e.g., "*.ts")'
+      },
+      maxDepth: {
+        type: 'number',
+        description: 'Maximum depth to traverse'
+      }
+    },
+    required: ['path']
+  },
+  async execute({ path, pattern, maxDepth = 3 }) {
+    let files = await fetchDirectoryListing(path, maxDepth);
+    
+    if (pattern) {
+      const minimatch = await import('minimatch');
+      files = files.filter(f => minimatch.default(f.name, pattern));
+    }
+    
+    return { files };
+  }
+};
+```
+
+## Adding New Tools
+
+### Step 1: Create the Tool File
+
+Create `tools/my_custom_tool.mjs`:
+
+```javascript
+export const myCustomTool = {
+  name: 'analyze_dependencies',
+  description: 'Analyze package.json dependencies and find outdated packages',
+  inputSchema: {
+    type: 'object',
+    properties: {
+      checkUpdates: {
+        type: 'boolean',
+        description: 'Check npm for newer versions'
+      }
+    }
+  },
+  async execute({ checkUpdates = false }) {
+    // Read package.json
+    const packageJson = await this.tools.read_file.execute({ 
+      path: 'package.json' 
+    });
+    
+    const pkg = JSON.parse(packageJson.content);
+    const deps = { ...pkg.dependencies, ...pkg.devDependencies };
+    
+    const result = {
+      total: Object.keys(deps).length,
+      dependencies: pkg.dependencies,
+      devDependencies: pkg.devDependencies
+    };
+    
+    if (checkUpdates) {
+      // Check for updates (simplified example)
+      result.outdated = await checkForUpdates(deps);
+    }
+    
+    return result;
+  }
+};
+```
+
+### Step 2: Register the Tool
+
+Edit `tools/index.mjs`:
+
+```javascript
+export { readFileTool } from './read_file.mjs';
+export { listFilesTool } from './list_files.mjs';
+export { searchCodeTool } from './search_code.mjs';
+export { getReadmeTool } from './get_readme.mjs';
+// Add your custom tool
+export { myCustomTool } from './my_custom_tool.mjs';
+```
+
+### Step 3: Add to Server
+
+Edit `server.mjs`:
+
+```javascript
+import { Server } from '@modelcontextprotocol/sdk/server/index.js';
+import * as tools from './tools/index.mjs';
+
+const server = new Server({
+  name: 'my-repo-mcp',
+  version: '1.0.0'
+});
+
+// Register all tools
+Object.values(tools).forEach(tool => {
+  server.setRequestHandler('tools/call', tool.name, tool.execute);
+});
+```
+
+## Tool Patterns
+
+### Composite Tools
+
+Create tools that combine multiple operations:
+
+```javascript
+export const explainCodeTool = {
+  name: 'explain_code',
+  description: 'Read a file and provide structured information about it',
+  inputSchema: {
+    type: 'object',
+    properties: {
+      path: { type: 'string' }
+    },
+    required: ['path']
+  },
+  async execute({ path }, { tools }) {
+    // Use other tools
+    const content = await tools.read_file.execute({ path });
+    const related = await tools.search_code.execute({ 
+      query: path.split('/').pop().replace('.', '') 
+    });
+    
+    return {
+      content: content.content,
+      relatedFiles: related.results.slice(0, 5),
+      lineCount: content.content.split('\n').length,
+      language: detectLanguage(path)
+    };
+  }
+};
+```
+
+### Tools with Side Effects
+
+For tools that modify state (use cautiously):
+
+```javascript
+export const createIssueTool = {
+  name: 'create_issue',
+  description: 'Create a GitHub issue (requires write access)',
+  inputSchema: {
+    type: 'object',
+    properties: {
+      title: { type: 'string' },
+      body: { type: 'string' },
+      labels: { type: 'array', items: { type: 'string' } }
+    },
+    required: ['title', 'body']
+  },
+  async execute({ title, body, labels = [] }, { config }) {
+    const response = await fetch(
+      `https://api.github.com/repos/${config.owner}/${config.repo}/issues`,
+      {
+        method: 'POST',
+        headers: {
+          Authorization: `token ${config.token}`,
+          'Content-Type': 'application/json'
+        },
+        body: JSON.stringify({ title, body, labels })
+      }
+    );
+    
+    return await response.json();
+  }
+};
+```
+
+### Paginated Tools
+
+Handle large result sets:
+
+```javascript
+export const searchCodeTool = {
+  name: 'search_code',
+  inputSchema: {
+    type: 'object',
+    properties: {
+      query: { type: 'string' },
+      page: { type: 'number', default: 1 },
+      perPage: { type: 'number', default: 30 }
+    },
+    required: ['query']
+  },
+  async execute({ query, page = 1, perPage = 30 }) {
+    const results = await searchGithubCode(query, page, perPage);
+    
+    return {
+      results: results.items,
+      total: results.total_count,
+      page,
+      perPage,
+      hasMore: results.total_count > page * perPage
+    };
+  }
+};
+```
+
+## TypeScript Tools
+
+For TypeScript servers, use proper types:
+
+```typescript
+import { Tool, ToolResult } from '@modelcontextprotocol/sdk';
+
+interface ReadFileInput {
+  path: string;
+}
+
+interface ReadFileOutput {
+  content: string;
+  encoding: string;
+}
+
+export const readFileTool: Tool<ReadFileInput, ReadFileOutput> = {
+  name: 'read_file',
+  description: 'Read file contents',
+  inputSchema: {
+    type: 'object',
+    properties: {
+      path: { type: 'string' }
+    },
+    required: ['path']
+  },
+  async execute(input: ReadFileInput): Promise<ToolResult<ReadFileOutput>> {
+    const content = await fetchFile(input.path);
+    return {
+      content,
+      encoding: 'utf-8'
+    };
+  }
+};
+```
+
+## Testing Custom Tools
+
+### Unit Testing
+
+```javascript
+import { describe, it, expect } from 'vitest';
+import { myCustomTool } from './my_custom_tool.mjs';
+
+describe('myCustomTool', () => {
+  it('should analyze dependencies', async () => {
+    const mockTools = {
+      read_file: {
+        execute: async () => ({
+          content: JSON.stringify({
+            dependencies: { 'lodash': '^4.0.0' }
+          })
+        })
+      }
+    };
+    
+    const result = await myCustomTool.execute(
+      { checkUpdates: false },
+      { tools: mockTools }
+    );
+    
+    expect(result.total).toBe(1);
+    expect(result.dependencies.lodash).toBe('^4.0.0');
+  });
+});
+```
+
+### Integration Testing
+
+```bash
+# Start the server
+node server.mjs &
+
+# Test with MCP inspector
+mcp-inspector ws://localhost:3000 --call analyze_dependencies
+```
+
+---
+
+## Best Practices
+
+1. **Keep tools focused** - One tool, one purpose
+2. **Validate inputs** - Check required fields and types
+3. **Handle errors gracefully** - Return meaningful error messages
+4. **Document well** - Clear descriptions help AI use tools correctly
+5. **Test thoroughly** - Both unit and integration tests
+
+---
+
+## Next Steps
+
+- [Batch Conversion](batch.md) - Convert multiple repos
+- [API Reference](../api/index.md) - Full programmatic API
+- [Architecture](../contributing/architecture.md) - How it all works

package/mkdocs/docs/guides/index.md

@@ -0,0 +1,78 @@
+# Guides
+
+Step-by-step tutorials for using GitHub to MCP with your favorite tools.
+
+## Integration Guides
+
+<div class="feature-grid" markdown>
+
+<div class="feature-card" markdown>
+
+### [Claude Desktop](claude-desktop.md)
+Connect your MCP server to Claude Desktop for powerful AI conversations about your codebase.
+
+</div>
+
+<div class="feature-card" markdown>
+
+### [Cursor](cursor.md)
+Integrate MCP servers with Cursor IDE for enhanced AI-assisted coding.
+
+</div>
+
+<div class="feature-card" markdown>
+
+### [VS Code](vscode.md)
+Use MCP servers with VS Code and GitHub Copilot.
+
+</div>
+
+</div>
+
+## Feature Guides
+
+<div class="feature-grid" markdown>
+
+<div class="feature-card" markdown>
+
+### [Private Repos](private-repos.md)
+Work with private repositories using GitHub authentication.
+
+</div>
+
+<div class="feature-card" markdown>
+
+### [Custom Tools](custom-tools.md)
+Modify and extend the generated MCP tools.
+
+</div>
+
+<div class="feature-card" markdown>
+
+### [Batch Conversion](batch.md)
+Convert multiple repositories at once.
+
+</div>
+
+</div>
+
+---
+
+## Quick Links
+
+| Guide | Best For |
+|-------|----------|
+| [Claude Desktop](claude-desktop.md) | General AI conversations, research |
+| [Cursor](cursor.md) | AI-assisted coding, refactoring |
+| [VS Code](vscode.md) | GitHub Copilot integration |
+| [Private Repos](private-repos.md) | Internal/proprietary codebases |
+| [Custom Tools](custom-tools.md) | Advanced users, API extensions |
+| [Batch Conversion](batch.md) | Multiple repos, automation |
+
+---
+
+## Need Help?
+
+- Check the [FAQ](../reference/index.md#faq)
+- Join the [GitHub Discussions](https://github.com/nirholas/github-to-mcp/discussions)
+- Report issues on [GitHub](https://github.com/nirholas/github-to-mcp/issues)