pedronauck/sourcebot

Sourcebot Guide

Expert guidance for using Sourcebot MCP to search external libraries, frameworks, and code patterns.

When to Use

• External library research: Finding code patterns in Effect-TS, TanStack, Vercel AI SDK, etc.
• API discovery: Understanding how external libraries implement specific features
• Documentation examples: Finding real-world usage examples from official repositories
• Framework patterns: Learning best practices from external framework codebases
• Migration guidance: Finding upgrade patterns and breaking changes in external libraries

When NOT to Use

• Local project code: Use codebase_search or osgrep search instead
• Local components: Use local search tools for project files
• Local utilities: Never use Sourcebot for your own codebase

Required Workflow

1. First, call list_repos to get available repository IDs
2. Identify relevant repository ID(s) for your search (e.g., "Effect-TS/effect" for EffectTS)
3. Always include filterByRepoIds when calling search_code
4. Use get_file_source to fetch specific file contents when needed

Repository ID Format

• CRITICAL: Repository IDs must be in format "owner/repo" (e.g., "Effect-TS/effect", "vercel/ai")
• DO NOT include the github.com/ prefix
• The list_repos tool returns IDs like "github.com/owner/repo" - strip the prefix when using in filterByRepoIds

Usage Examples

Searching EffectTS patterns

{
  "query": "Effect.gen yield",
  "filterByRepoIds": ["Effect-TS/effect"],
  "includeCodeSnippets": true
}

Searching AI SDK

{
  "query": "streamText tool calling",
  "filterByRepoIds": ["vercel/ai"],
  "includeCodeSnippets": true
}

Searching multiple repos

{
  "query": "error handling patterns",
  "filterByRepoIds": ["Effect-TS/effect", "vercel/ai"],
  "includeCodeSnippets": true
}

Best Practices

• Use descriptive queries (not just keywords, but full descriptions)
• Always specify filterByRepoIds to scope searches
• Set includeCodeSnippets: true when you need actual code examples
• Use get_file_source after finding relevant files to see full context

Tool Hierarchy for Code Search

1. Sourcebot - For EXTERNAL libraries and frameworks only
2. codebase_search (if available) - For local project code
3. osgrep search - For local code when codebase_search unavailable
4. grep/find - Last resort for exact string matching

Critical Requirements

• MANDATORY: Use Sourcebot MCP 5-7 times when researching external libraries
• CRITICAL: NEVER use Sourcebot to search local project code
• CRITICAL: Always use filterByRepoIds on EVERY search_code call
• TASK INVALIDATION: Task will be invalidated if you don't use Sourcebot 5-7 times when dealing with external libraries
• AFTER SOURCEBOT: Also use Perplexity and Context7 for updated information on external libraries