Getting Started

Go from AI that does not know your docs to AI expert on your codebase in under 5 minutes

Your AI Will Know Your Entire Codebase in 5 Minutes

Right now: Your AI hallucinates patterns. You copy-paste docs every session. New developers ask the same questions for weeks.

5 minutes from now: Your AI assistant has instant access to every README, wiki page, and architecture doc across all your repositories.

This guide gets you there—fast.

---

What You’ll Accomplish

Connect GitHub

2 minutes

OAuth connection → automatic repository discovery

Index Documentation

1-3 minutes (automatic)

AI processes all your docs in the background

Configure AI Tool

2 minutes

Add ULPI MCP server to Claude Code, Cursor, or 40+ other tools

Ask First Question

Instant answers

“How do we deploy?” → Your AI knows immediately

Total time: 5-7 minutes. Most of it is waiting for automatic indexing.

---

Prerequisites

You’ll need:

Required

GitHub Account

Sign up free at github.com

Works with personal or organization accounts

AI Coding Assistant

Any MCP-compatible tool:

• Claude Desktop (recommended)
• Cursor
• Windsurf
• VSCode with Continue/Cline
• See all 40+ tools

Repository requirements:

• Public or private repositories (both supported)
• GitHub, GitLab, Bitbucket, or Gitea
• Documentation in Markdown, README files, wikis, or code comments

---

Step 1: Create Your ULPI Account

Stop wasting time searching. Let’s fix this now.

1. Visit app.ulpi.io

   Go to app.ulpi.io and click Sign Up

   No credit card required for signup. Choose your plan after you see the value.

2. Authenticate with GitHub

   Click Continue with GitHub to authenticate via OAuth

   What we request:

   • ✅ Read-only access to repositories
   • ✅ Webhook access (for auto-sync)
   • ❌ We never write to your code
   • ❌ We never modify repositories

   Using GitLab, Bitbucket, or Gitea? Select “Other Git Provider” and follow the connection wizard.

3. Choose Your Plan

   Select a plan based on your team size:

   Starter ($29/mo)

   Perfect for solo developers or small teams:

   • 5 repositories
   • 100,000 tokens/month (~15-20 searches/day)
   • Semantic search across all docs
   • Auto-sync on every push
   • MCP integration (40+ AI tools)
   • Email support

   Best for: 1-3 developers

   Compare all plans in detail →

   Not sure? Start with Starter. Upgrade anytime. We’ll prorate the difference.

   Bundle discount: Save 15-20% by combining Documentation with Skills, Memory, Coordination, or Hooks.

4. Complete Billing

   Enter payment details via Stripe (secure, PCI-compliant)

   Guarantees:

   • 🔒 Bank-level security (PCI-DSS Level 1)
   • 💳 30-day money-back - cancel anytime, full refund
   • 🔄 Flexible billing - change plans monthly
   • 📊 Transparent usage - see token consumption in real-time

   Your account is live immediately after payment confirmation.

Estimated time: 2 minutes

---

Step 2: Connect Your Repositories

Make your documentation searchable by AI.

1. Navigate to Repositories

   In the ULPI dashboard:

   1. Click Repositories in the left sidebar
   2. You’ll see the repository connection screen

   If you just signed up, you’ll be automatically directed here.

2. Select Repositories to Connect

   Choose which repositories to make searchable:

   Select Individual Repos

   Best for testing or specific projects:

   1. Browse your repositories in the list
   2. Check the boxes next to repositories with documentation
   3. Click Connect Selected (green button)

   Recommended for first-time setup: Start with 2-3 repos to see ULPI in action, then add more.

3. Grant Permissions

   ULPI requests authorization to:

   ✅ Read Repository Contents

   What we read:

   • Documentation files (.md, .mdx, README.*)
   • Wiki pages (optional, you can disable)
   • Code comments (optional, disabled by default)

   What we don’t read:

   • Source code (unless you enable comment indexing)
   • Secrets, .env files
   • Build artifacts, node_modules/
   • Binary files

   ✅ Receive Webhook Notifications

   Why we need this:

   • Automatic re-indexing on git push
   • Keep documentation always up-to-date
   • No manual “sync” button needed

   Triggered on:

   • Push to main/master branch
   • Pull request merges
   • Wiki updates
   • Manual trigger from dashboard

   ❌ We Never Write to Your Code

   Security guarantee:

   • ❌ Cannot modify files
   • ❌ Cannot create commits
   • ❌ Cannot push changes
   • ❌ Cannot delete repositories

   Read-only access only. Revoke anytime from GitHub settings.

   Click Authorize ULPI to proceed.

4. Wait for Initial Indexing

   ULPI automatically discovers and indexes your documentation:

   What Gets Indexed

   Automatically included:

   • ✅ README.md, README.txt (all directories)
   • ✅ docs/ and documentation/ directories
   • ✅ All .md and .mdx files
   • ✅ CONTRIBUTING.md, CHANGELOG.md
   • ✅ Architecture Decision Records (ADRs)
   • ✅ .github/ documentation

   Optionally included (configure in settings):

   • 🔧 Wiki pages (disabled by default, can enable)
   • 🔧 Code comments and docstrings (disabled by default)
   • 🔧 Jupyter notebooks (.ipynb)
   • 🔧 .txt files in doc directories

   Automatically excluded:

   • ❌ node_modules/, vendor/, packages/
   • ❌ Build directories (dist/, build/, out/)
   • ❌ .git/ directory
   • ❌ Binary files (images, PDFs, etc.)
   • ❌ Large files (>1MB)

   Custom exclusions: Create a .ulpiignore file (works like .gitignore)

Estimated time: 2 minutes to connect, 1-15 minutes for automatic indexing

Troubleshooting: Repository not appearing in list

If you don’t see your repository:

1. Check GitHub OAuth permissions:

   • Go to github.com/settings/applications
   • Find “ULPI Documentation”
   • Ensure it has access to the organization
   • Click “Grant access” if needed

2. Organization settings:

   • Org admin must approve third-party apps
   • Ask your GitHub org admin to approve ULPI
   • Guide for admins →

3. Repository visibility:

   • Private repos require explicit OAuth permission
   • Re-authenticate and grant access to private repositories

4. Still not working?

   • Contact support: [e-mail]
   • Include: repository URL, GitHub username, error messages

---

Step 3: Create an API Key

API keys connect your AI assistant to ULPI’s documentation search.

1. Navigate to API Keys

   In the ULPI dashboard:

   1. Click Settings in sidebar
   2. Select API Keys tab
   3. You’ll see the API key management screen
2. Click Create API Key

   Click the Create API Key button (green button, top right)

3. Configure Key Settings

   Fill in API key details:

   Basic Settings

   Name: Documentation MCP Server

   (For identification—name it after where you’ll use it)

   Examples:

   • “Claude Desktop - MacBook Pro”
   • “Cursor - Work Laptop”
   • “Team Shared Key”

   ---

   Environment: live (production) or test (development)

   • live: Use in real AI assistants (recommended)
   • test: Use for testing, development, experiments

   Start with live environment unless you’re developing integrations.

4. Copy Your API Key

   ⚠️ CRITICAL: This is shown ONLY ONCE!

   1. Copy the API key immediately
   2. Store it securely:
      • Password manager (1Password, LastPass, Bitwarden)
      • Environment variable in your shell config
      • Secure note in your IDE

   API key format: ulpi_live_sk_1234abcd...

   Never commit API keys to version control!

   Add to .gitignore:

   # ULPI API Keys
   .env
   .env.local
   **/mcp_config.json
   claude_desktop_config.json
   

   Lost your key? You can’t recover it, but you can:

   1. Revoke the old key
   2. Create a new one
   3. Update your AI tool config with the new key

Estimated time: 1 minute

---

Step 4: Configure Your AI Assistant

Connect ULPI to your favorite AI coding tool.

Choose your AI assistant below and follow the setup:

Claude Desktop (Recommended)

Anthropic’s official AI assistant with best ULPI integration

1. Locate Config File

   Find your Claude Desktop config file:

   macOS

   ~/Library/Application Support/Claude/claude_desktop_config.json
   

   Open in terminal:

   open ~/Library/Application\ Support/Claude/
   

2. Add ULPI MCP Server

   Edit claude_desktop_config.json:

   {
     "mcpServers": {
       "ulpi-docs": {
         "command": "npx",
         "args": ["-y", "@ulpi/mcp-server-documentation"],
         "env": {
           "ULPI_API_KEY": "ulpi_live_YOUR_KEY_HERE"
         }
       }
     }
   }
   

   Replace ulpi_live_YOUR_KEY_HERE with your actual API key from Step 3.

   Already have other MCP servers?

   Add ULPI to existing config:

   {
     "mcpServers": {
       "filesystem": {
         "command": "npx",
         "args": ["-y", "@modelcontextprotocol/server-filesystem"]
       },
       "ulpi-docs": {
         "command": "npx",
         "args": ["-y", "@ulpi/mcp-server-documentation"],
         "env": {
           "ULPI_API_KEY": "ulpi_live_sk_abc123..."
         }
       },
       "github": {
         "command": "npx",
         "args": ["-y", "@modelcontextprotocol/server-github"]
       }
     }
   }
   

   Just add the ulpi-docs block to your existing mcpServers object.

3. Restart Claude Desktop

   1. Quit Claude Desktop completely (Cmd+Q on Mac, Alt+F4 on Windows)
   2. Reopen Claude Desktop
   3. Look for 🔌 MCP icon in bottom toolbar (indicates servers loaded)

   Success indicator: You’ll see “MCP: 1 server connected” or “ulpi-docs” in the MCP status panel.

Total time: 2 minutes

Detailed Claude Desktop guide →

Estimated time: 2 minutes

---

Step 5: Test Your First Search

Verify everything works!

1. Open Your AI Assistant

   Launch the AI tool you configured in Step 4:

   • Claude Desktop
   • Cursor
   • VSCode with Continue/Cline
   • etc.
2. Ask a Documentation Question

   Try these example queries:

   Environment Setup

   "How do I set up the local development environment?"
   

   Ask in plain English! ULPI understands natural language—no need for exact keywords.

3. Verify Results

   Your AI assistant should:

   ✅ Search ULPI automatically (you won’t see this, it happens behind the scenes)

   ✅ Return relevant documentation excerpts from your repositories

   ✅ Include source file links like:

   Based on docs/setup.md:15-45:
   To set up your development environment...
   

   ✅ Provide context-aware answers using YOUR project’s patterns

   ✅ Cite multiple sources if the answer spans multiple docs

   Success looks like: AI responds with specific details from your actual documentation, not generic advice.

4. Monitor in Dashboard

   See searches in real-time:

   1. Go to ULPI dashboard → Activity tab
   2. You’ll see:
      • Recent searches
      • Which repositories were queried
      • Token usage
      • Response times

   Example activity log:

   10:34 AM - Search: "How do we deploy?"
              → Found in: infrastructure/deployment.md
              → Tokens used: 2,340
              → Response time: 45ms
   
   10:31 AM - Search: "API authentication methods"
              → Found in: backend-api/README.md, docs/auth.md
              → Tokens used: 1,890
              → Response time: 38ms
   

Estimated time: 1 minute

---

Troubleshooting

🚨 AI Assistant Doesn't Search ULPI

Symptom: AI gives generic answers instead of searching your docs.

Fixes:

1. Check MCP server connection:

   • Claude Desktop: Look for 🔌 icon in bottom toolbar
   • Cursor: Check Settings → MCP Servers shows “Connected”
   • VSCode: Continue/Cline should show “ulpi-docs” in status

2. Verify API key format:

   {
     "env": {
       "ULPI_API_KEY": "ulpi_live_sk_abc123..."  // ✅ Correct
     }
   }
   

   Common errors:

   "ULPI_API_KEY": " ulpi_live_sk_abc123"  // ❌ Leading space
   "ULPI_API_KEY": "ulpi_test_sk_abc123"   // ❌ Wrong environment
   "ULPI_API_KEY": "'ulpi_live_sk_abc123'" // ❌ Extra quotes
   

3. Check MCP server logs:

   • macOS: ~/Library/Logs/Claude/mcp.log
   • Windows: %APPDATA%\Claude\Logs\mcp.log
   • Linux: ~/.config/Claude/logs/mcp.log

   Look for errors like:

   ERROR: Authentication failed - invalid API key
   ERROR: ULPI_API_KEY environment variable not set
   ERROR: Network error connecting to ULPI API
   

4. Restart AI assistant:

   • Fully quit (don’t just close window)
   • Reopen and try again
   • Config changes only load on full restart

⏱️ Indexing Taking Too Long

Symptom: Repository stuck at “Indexing…” for >30 minutes.

Normal indexing times:

• Less than 100 files: 30 seconds - 2 minutes
• 100-1,000 files: 2-5 minutes
• 1,000-10,000 files: 5-15 minutes
• 10,000+ files: 15-30 minutes

If it’s taking longer:

1. Check repository size:

   • Dashboard → Repositories → Click repo name
   • See “Files discovered” count
   • Large repos (10,000+ files) can take 30-45 minutes

2. Check for errors:

   • Look for ⚠️ warning icon next to repository
   • Click for error details
   • Common issues:
     • Binary files causing slowdown (auto-excluded, but takes time to detect)
     • Network issues accessing GitHub
     • Very large markdown files (>5MB)

3. Force re-index:

   • Dashboard → Repositories → Click ⟳ Re-index button
   • This restarts the indexing process
   • Sometimes resolves stuck states

4. Contact support:

   • If stuck >1 hour: [e-mail]
   • Include: repository name, size, approximate file count

🔍 Search Returns No Results

Symptom: AI says “I couldn’t find documentation about that” or returns empty results.

Possible causes:

1. Indexing not complete:

   • Dashboard → Repositories → Check status
   • Wait for ”✅ Indexed” status
   • Usually takes 2-5 minutes

2. Documentation doesn’t exist:

   • Verify your repos actually have docs about that topic
   • Check if docs use different terminology
   • Example: You ask about “authentication” but docs say “auth” or “login”

3. Wrong repository scope:

   • API key might be scoped to specific repos
   • Dashboard → Settings → API Keys → Check scopes
   • Expand scope or use different key

4. Query too vague:

   • ❌ “How does it work?”
   • ✅ “How does authentication work?”
   • ✅ “Explain our Redis caching strategy”
   • Be specific!

5. Files excluded by default:

   • Check .ulpiignore file in repository
   • Dashboard → Repositories → Click repo → See “Excluded patterns”
   • Adjust exclusions if needed

🔑 API Key Issues

Symptom: “Invalid API key” or authentication errors.

Fixes:

1. Verify key format:

   ulpi_live_sk_1234567890abcdef...  // ✅ Correct (live)
   ulpi_test_sk_1234567890abcdef...  // ✅ Correct (test)
   ulpi_sk_1234567890abcdef...       // ❌ Missing environment
   sk_1234567890abcdef...             // ❌ Missing ulpi_ prefix
   

2. Check environment match:

   • API key environment (live vs test)
   • MCP server environment
   • Dashboard shows environment per key

3. Verify key not revoked:

   • Dashboard → Settings → API Keys
   • Check key status is “Active” (not “Revoked”)
   • If revoked, create a new key

4. Test API key directly:

   curl -H "Authorization: Bearer ulpi_live_sk_YOUR_KEY" \
        https://api.ulpi.io/v1/search?q=test
   

   Expected response:

   {
     "success": true,
     "results": [...]
   }
   

   Error response:

   {
     "error": "Invalid API key"
   }
   

💾 Token Limit Exceeded

Symptom: “You’ve exceeded your monthly token limit” error.

Solutions:

1. Check current usage:

   • Dashboard → Usage & Billing
   • See tokens used vs. plan limit
   • View usage by day/week/month

2. Upgrade plan:

   • Starter (100k) → Professional (500k)
   • Professional → Enterprise (2M)
   • Settings → Billing → Change Plan

3. Buy token overage:

   • $20 per 100,000 additional tokens
   • No service interruption
   • Automatically billed at end of month
   • Dashboard → Usage → “Buy More Tokens”

4. Set usage alerts:

   • Dashboard → Settings → Usage Alerts
   • Get notified at 50%, 75%, 90% of limit
   • Prevents surprises

5. Optimize searches:

   • Be more specific in queries (returns less data)
   • Scope searches to specific repositories
   • Avoid overly broad questions

🔒 Repository Access Denied

Symptom: “Access denied” when trying to search private repositories.

Fixes:

1. Re-authenticate with GitHub:

   • Dashboard → Settings → Integrations
   • Click “Reconnect GitHub”
   • Grant access to private repositories

2. Check organization approval:

   • GitHub org admin must approve ULPI app
   • Ask admin to:
     1. Go to github.com/organizations/YOUR_ORG/settings/oauth_application_policy
     2. Find “ULPI Documentation”
     3. Click “Grant access”

3. Verify API key scope:

   • Dashboard → Settings → API Keys
   • Click key name → View scopes
   • Ensure key has access to that repository

4. Repository permissions:

   • You must have at least “Read” access to repo in GitHub
   • Org admins can grant access via GitHub teams

🌐 Network / Firewall Issues

Symptom: Connection timeouts or “Cannot reach ULPI API” errors.

Enterprise network fixes:

1. Whitelist ULPI domains:

   api.ulpi.io
   app.ulpi.io
   *.ulpi.io
   

2. Allow outbound HTTPS (port 443):

   • ULPI MCP server needs to reach api.ulpi.io:443
   • Check corporate firewall rules

3. Proxy configuration:

   {
     "env": {
       "ULPI_API_KEY": "ulpi_live_sk_...",
       "HTTPS_PROXY": "http://proxy.company.com:8080",
       "HTTP_PROXY": "http://proxy.company.com:8080"
     }
   }
   

4. VPN conflicts:

   • Try disconnecting VPN temporarily
   • If works without VPN, configure VPN to allow ULPI

5. Test connectivity:

   curl -I https://api.ulpi.io/health
   

   Expected: HTTP 200 OK Error: Connection timeout or refused

Still stuck? Email [e-mail] with:

• Error message screenshot
• MCP server logs
• API key (first/last 4 characters only)
• AI tool and OS you’re using

---

What’s Next?

Advanced Search Features

Master semantic search, filters, and query optimization

Learn: Cross-repo search, branch filtering, date ranges, file type filters

How It Works (Technical Deep Dive)

Understand the architecture behind ULPI’s semantic search

Learn: Vector embeddings, Typesense, chunking strategies, indexing pipeline

Repository Management

Add more repositories, configure indexing, manage webhooks

Learn: Multi-repo strategies, .ulpiignore, custom exclusions, wiki integration

API Integration

Integrate ULPI directly into your applications via REST API

Learn: Direct API access, custom search UIs, workflow automation

---

Success Story

Your team’s documentation is searchable now. Time to see the same transformation.

---

Need help? We’re here for you:

• 📧 Email: [e-mail]
• 📚 Docs: docs.ulpi.io
• 💬 Slack Community: ulpi.io/slack
• 🐛 Bug Reports: github.com/ulpi-io/feedback

Average response time: Under 2 hours during business hours