Fetches and analyzes GitHub repositories to identify core abstractions and generate comprehensive tutorials with Mermaid diagrams.
Supports Google Gemini as an LLM provider for repository analysis and tutorial generation.
Generates Mermaid flowcharts and sequence diagrams to visualize code architecture in tutorials.
Supports OpenAI models like GPT-4o as an LLM provider for repository analysis and tutorial generation.
Click on "Deploy Server".
Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state.
In the chat, type @ followed by the MCP server name and your instructions, e.g., "@PocketFlow MCP Server analyze https://github.com/expressjs/express and create a beginner tutorial"
That's it! The server will respond to your query, and you can continue using it as needed.
Here is a step-by-step guide with screenshots.
A Model Context Protocol (MCP) server that brings the powerful PocketFlow tutorial generation methodology to all AI assistants. Generate comprehensive, beginner-friendly tutorials from any GitHub repository using advanced AI analysis.
PocketFlow is an innovative methodology for automatically generating high-quality tutorials from codebases. It:
Identifies Core Abstractions - Finds the key concepts and components in a codebase
Maps Relationships - Understands how different parts interact with each other
Orders Explanations - Determines the best sequence to explain concepts
Generates Tutorials - Creates beginner-friendly, step-by-step learning content
Creates Visual Diagrams - Includes Mermaid diagrams for better understanding
Related MCP server: TypeScript Prompt MCP Server
✅ Universal AI Assistant Support - Works with Cline, Cursor, Claude Desktop, and any MCP-compatible client
🔍 Deep Repository Analysis - Analyzes GitHub repositories to identify key abstractions
🧠 Intelligent Concept Mapping - Understands relationships between code components
📚 Comprehensive Tutorial Generation - Creates structured, beginner-friendly tutorials
📊 Visual Architecture Diagrams - Generates Mermaid flowcharts and sequence diagrams
🌐 Multi-LLM Provider Support - OpenRouter, Google Gemini, Anthropic Claude, OpenAI
🌍 Multi-Language Support - Generate tutorials in different languages
🔒 Secure & Local - All processing happens locally, API keys stored securely
⚡ Smart Caching - Caches LLM responses for faster subsequent runs
Node.js 18+
npm or yarn
An API key for your preferred LLM provider
Clone and Build
git clone https://github.com/tmtcomeup/pocketflow-mcp.git
cd pocketflow-mcp
npm install
npm run buildConfigure Your AI Assistant
Add to your Cline settings:
{
"mcpServers": {
"pocketflow": {
"command": "node",
"args": ["path/to/pocketflow-mcp/build/index.js"]
}
}
}Add to claude_desktop_config.json:
{
"mcpServers": {
"pocketflow": {
"command": "node",
"args": ["path/to/pocketflow-mcp/build/index.js"]
}
}
}Once connected, you'll have access to these tools:
analyze_github_repositoryGenerate a complete tutorial from any GitHub repository:
// Basic usage
analyze_github_repository({
repo_url: "https://github.com/microsoft/vscode",
llm_provider: "openrouter",
api_key: "sk-or-v1-your-key-here",
model: "anthropic/claude-3.5-sonnet"
})
// Advanced options
analyze_github_repository({
repo_url: "https://github.com/pytorch/pytorch",
llm_provider: "google",
api_key: "your-gemini-key",
model: "gemini-2.5-pro",
max_abstractions: 8,
language: "spanish",
include_patterns: ["*.py", "*.md"],
exclude_patterns: ["*test*", "*docs/*"]
})get_repository_structureExplore repository structure before analysis:
get_repository_structure({
repo_url: "https://github.com/facebook/react",
include_patterns: ["*.js", "*.jsx", "*.ts"],
max_depth: 3
})Sign up at openrouter.ai
Get your API key from the dashboard
Access 100+ models including Claude, GPT-4, Gemini, and more
Get an API key from Google AI Studio
Use models like gemini-2.5-pro or gemini-2.5-flash
Get an API key from console.anthropic.com
Use models like claude-3-5-sonnet-20241022
Get an API key from platform.openai.com
Use models like gpt-4o or gpt-4o-mini
The PocketFlow methodology follows a 6-step process:
Repository Fetching - Downloads and filters code files based on patterns
Abstraction Identification - Uses AI to identify 5-10 core concepts in the codebase
Relationship Analysis - Maps how abstractions interact with each other
Chapter Ordering - Determines the optimal learning sequence
Chapter Writing - Generates detailed, beginner-friendly explanations for each concept
Tutorial Compilation - Combines everything into a cohesive tutorial with diagrams
The generated tutorial includes:
Index Page with project overview and visual architecture diagram
Individual Chapters for each core abstraction
Mermaid Diagrams showing relationships and workflows
Code Examples with detailed explanations
Cross-References between related concepts
Beginner-Friendly Language with analogies and examples
Parameter | Description | Default |
| GitHub repository URL | Required |
| AI provider ( | Required |
| API key for the LLM provider | Required |
| Specific model to use | Provider default |
| Number of key concepts to identify | 10 |
| Tutorial language | "english" |
| File patterns to analyze | Common code files |
| File patterns to skip | Tests, docs, builds |
| Maximum file size in bytes | 100000 |
| Enable LLM response caching | true |
We welcome contributions! Please see our contributing guidelines.
MIT License - see LICENSE file for details.
This MCP server is based on the original PocketFlow project by The-Pocket. We've adapted their brilliant methodology to work seamlessly with all MCP-compatible AI assistants.
🐛 Bug Reports: GitHub Issues
💬 Discussions: GitHub Discussions
📖 Documentation: Check this README and inline code comments
Ready to transform any codebase into a comprehensive learning resource? Start analyzing repositories with PocketFlow MCP today!
Analyze a GitHub repository and generate a comprehensive tutorial following the PocketFlow methodology
| Name | Required | Description | Default |
|---|---|---|---|
| api_key | Yes | API key for the LLM provider | |
| exclude_patterns | No | File patterns to exclude (e.g., ["*test*", "*docs/*"]) | |
| github_token | No | Optional GitHub token for private repos or rate limit avoidance | |
| include_patterns | No | File patterns to include (e.g., ["*.py", "*.js"]) | |
| language | No | Language for tutorial generation | english |
| llm_provider | Yes | LLM provider to use for analysis | |
| max_abstractions | No | Maximum number of abstractions to identify | |
| max_file_size | No | Maximum file size in bytes | |
| model | No | Specific model to use (e.g., "anthropic/claude-3.5-sonnet" for OpenRouter or "gemini-2.5-pro" for Google) | gemini-2.5-pro |
| project_name | No | Optional project name (derived from repo if omitted) | |
| repo_url | Yes | GitHub repository URL (e.g., https://github.com/user/repo) | |
| use_cache | No | Enable LLM response caching |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description carries full burden but lacks critical behavioral details. It doesn't disclose that this is a complex, multi-step operation involving LLM calls, file processing, and potential rate limits. No information about execution time, error handling, or what 'comprehensive tutorial' entails is included.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, efficient sentence that clearly states the tool's purpose. It's appropriately sized and front-loaded with the core functionality, though it could benefit from additional context about the PocketFlow methodology.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a complex tool with 12 parameters, no annotations, and no output schema, the description is insufficient. It doesn't explain what the tutorial output looks like, how the analysis works, performance characteristics, or error conditions. The agent lacks crucial context for proper tool selection and invocation.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, so parameters are well-documented in the schema itself. The description adds no additional parameter context beyond implying the tool analyzes repository content for tutorial generation. This meets the baseline for high schema coverage.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the specific action ('analyze a GitHub repository') and the outcome ('generate a comprehensive tutorial following the PocketFlow methodology'). It distinguishes from the sibling tool 'get_repository_structure' by focusing on analysis and tutorial generation rather than just structural retrieval.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
No guidance is provided on when to use this tool versus alternatives. While it implicitly suggests use for tutorial generation, there's no mention of prerequisites (e.g., needing API keys), limitations, or comparison with the sibling tool 'get_repository_structure'.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Get the file structure of a GitHub repository
| Name | Required | Description | Default |
|---|---|---|---|
| exclude_patterns | No | File patterns to exclude | |
| github_token | No | Optional GitHub token | |
| include_patterns | No | File patterns to include | |
| max_depth | No | Maximum directory depth | |
| repo_url | Yes | GitHub repository URL |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description carries full burden for behavioral disclosure but offers minimal information. It doesn't mention authentication requirements (though github_token parameter suggests optional auth), rate limits, what format the structure is returned in, whether this is a read-only operation, or any side effects. 'Get' implies a read operation, but this isn't explicitly stated.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, efficient sentence that states the core purpose without unnecessary words. It's appropriately sized for a tool with good schema documentation and gets straight to the point. Every word earns its place.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a tool with 5 parameters, no annotations, and no output schema, the description is insufficient. It doesn't explain what format the structure is returned in (tree, list, JSON?), doesn't mention authentication behavior despite the github_token parameter, and provides no context about performance, limitations, or error conditions. The agent would need to guess about important behavioral aspects.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
With 100% schema description coverage, all parameters are documented in the schema itself. The description adds no additional parameter semantics beyond what the schema provides - it doesn't explain how patterns work, what depth means practically, or provide examples. The baseline of 3 is appropriate when the schema does the heavy lifting.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the action ('Get') and resource ('file structure of a GitHub repository'), making the purpose immediately understandable. However, it doesn't differentiate from the sibling tool 'analyze_github_repository' - we can infer this tool focuses on structure while the sibling might analyze content or metrics, but this distinction isn't explicit in the description.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides no guidance about when to use this tool versus the sibling 'analyze_github_repository' or any other alternatives. It doesn't specify prerequisites (like authentication needs) or contextual constraints beyond what's implied by the tool name. The agent must infer usage from the tool name alone.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
v1.0.0analyze_github_repositoryget_repository_structureScored across 2 tools
The two tools have clearly distinct purposes: analyze_github_repository generates a tutorial, while get_repository_structure retrieves file structure. There is no overlap or ambiguity between these functions, making it easy for an agent to select the correct tool.
Both tools follow a consistent verb_noun pattern (analyze_github_repository, get_repository_structure) with clear, descriptive names. The naming is uniform and predictable, enhancing usability.
With only 2 tools, the server feels thin for its apparent domain of GitHub repository analysis and tutorial generation. A more complete set might include tools for updating tutorials, managing analysis results, or handling other repository aspects, suggesting an under-scoped implementation.
The tool surface is severely incomplete for the PocketFlow methodology domain. It lacks essential operations such as creating, updating, or deleting tutorials, managing user interactions, or handling errors, which are likely needed for a comprehensive workflow, leading to potential agent failures.
Connect AI assistants to GitHub - manage repos, issues, PRs, and workflows through natural language.
Connect AI assistants to your GitHub-hosted Obsidian vault to seamlessly access, search, and analy…
Ask any GitHub repository a question. Get source-backed answers.
Code intelligence for LLMs. Analyze, search, and retrieve code from any public git repository.
