API Toolkit

API工具包-MCP服务器的轻量级替代方案

🔴 重要提示：请先检查安装状态！

在执行任何操作之前，请检查工具包是否已安装：

# Quick check (recommended)
bash /path/to/api-toolkit/check-installation.sh

# Or manual check
ls -la api-toolkit/

# If you see the directory, IT'S ALREADY INSTALLED!
# Skip to the "Usage Examples" section below.
# DO NOT run install.sh again!

如果尚未安装：

/path/to/api-toolkit/install.sh

______________________________________________________________________

🚀 快速入门（适用于任何用户/LLM）

工具包新手？ 看 SETUP_GUIDE.md 完整的5分钟演练。

步骤1：在项目中安装

cd /path/to/your/project
/path/to/api-toolkit/install.sh
# Choose option 1 (symlink recommended)

步骤2：在项目根目录中创建.env文件

# Copy template to YOUR project directory (not api-toolkit/)
cp api-toolkit/.env.example .env

# Add your API keys
nano .env

步骤3：测试它是否有效

# Check which .env was loaded and credential status
python api-toolkit/test-env-loading.py

# Try a query
python -c "from api_toolkit.services.supabase.api import SupabaseAPI; SupabaseAPI('project1').quick_start()"

完成！ 现在在代码中使用它：

from api_toolkit.services.supabase.api import SupabaseAPI
api = SupabaseAPI('project1')
leads = api.query('leads', limit=10)

故障排除？ 看 ENV_故障排除.md

______________________________________________________________________

🚀 比MCP效率高180倍

MCP服务器：每个对话中加载90000个令牌 API工具包：仅在需要时加载500-1000个令牌

⚡ 新功能：零摩擦体验

# Start with ANY project in 5 seconds!
from api_toolkit.services.supabase.api import SupabaseAPI

api = SupabaseAPI('project1')
api.quick_start()  # Shows tables, columns, filters, EVERYTHING!

# Bulletproof discovery - always works
info = api.discover()          # All tables
info = api.discover('users')   # Table details with columns & samples

# Raw SQL for complex queries
results = api.raw_query("SELECT * FROM users WHERE age > 18")

# API returns LIST directly, not {'data': [...]}
users = api.query('users')     # users is a list, NOT dict!

为什么存在

MCP服务器很方便，但会破坏您的上下文预算。此工具包提供以下功能：

• 最小令牌使用量 -只加载您需要的内容
• 您的内置图案 -为您的工作流程量身定制
• 渐进式加载 -快速参考或完整细节
• 从使用中学习 -自动记录成功的模式

______________________________________________________________________

🤖 克劳德代码：三步启动

每次新对话，请先运行以下命令：

# Step 1: Check installation (2 seconds)
ls -la api-toolkit/
# ✅ See files? Already installed! Continue to step 2.
# ❌ "No such file"? Run: /path/to/api-toolkit/install.sh

# Step 2: Read project config (3 seconds)
cat .api-toolkit-config.md
# Look for services marked: ✅ Active
# ONLY use those services (ignore ⚪ Not Configured)

# Step 3: Quick health check (5 seconds)
python -c "from api_toolkit.services.supabase.api import SupabaseAPI; SupabaseAPI('project1').quick_start()"

严重： API退货 直接列出，不 {'data': [...]} 格式！

users = api.query('users')  # users is a list
for user in users:          # NOT users['data']
    print(user['email'])

______________________________________________________________________

快速开始

🔍 详细的启动顺序

# 1. Check if toolkit is installed in current project
ls -la api-toolkit 2>/dev/null || echo "Not installed - run: /path/to/api-toolkit/install.sh"

# 2. Check project configuration (which services are active)
cat .api-toolkit-config.md 2>/dev/null || echo "No project config - create one: /path/to/api-toolkit/init-project.sh"

# 3. Test connections for active services
python api-toolkit/toolkit.py supabase test

# 4. Explore what's available
python api-toolkit/services/supabase/api.py explore smoothed

# 5. Check schema before querying
python api-toolkit/services/supabase/api.py schema smoothed leads

# 6. Query with confidence
python api-toolkit/toolkit.py supabase query smoothed leads

📋 项目配置

每个项目都应该有一个 .api-toolkit-config.md 声明哪些服务处于活动状态的文件：

# Create project configuration
/path/to/api-toolkit/init-project.sh

# This creates .api-toolkit-config.md with:
# - Which services are active for THIS project
# - Project-specific patterns and queries
# - Progress tracking across conversations
# - Integration documentation

# See full guide: PROJECT_CONFIG_GUIDE.md

📊 数据库发现模式（请先使用此模式！）

# ALWAYS start with exploration to avoid errors
from api_toolkit.services.supabase.api import SupabaseAPI

# Step 1: Connect and explore
api = SupabaseAPI('project1')  # or 'project2' or 'project3'
api.explore()  # Shows all tables

# Step 2: Check schema before querying
schema = api.get_schema('table_name')
for col in schema:
    print(f"{col['column']}: {col['type']}")

# Step 3: Use QueryBuilder for clean queries
from api_toolkit.services.supabase.query_helpers import QueryBuilder

query = (QueryBuilder('table_name')
         .select('column1', 'column2')  # Only columns that exist!
         .where('status', '=', 'active')
         .limit(10))

results = query.execute(api)

可用服务

安装

1. 导航到toolkit目录：

cd /path/to/api-toolkit

1. 安装依赖项：

pip install -r requirements.txt

1. 配置API密钥 -创建 .env 在项目根目录中：

# In YOUR project directory (not in api-toolkit/):
cd /path/to/your/project

# Copy the template
cp api-toolkit/.env.example .env

# Edit with your actual API keys
nano .env  # or vim, code, etc.

在哪里放置.env：

your-project/
├── .env                    ← Create here (recommended)
├── api-toolkit/           ← Symlink or copy
└── main.py

1. 测试您的配置：

# Shows which .env is loaded and credential status
python api-toolkit/test-env-loading.py

# Test specific service
python api-toolkit/toolkit.py supabase test

备选方案： 在中使用系统环境变量 ~/.zshrc 或 ~/.bashrc:

export SUPABASE_URL="your-url"
export SUPABASE_SERVICE_ROLE_KEY="your-key"
# ... etc

用法示例

🎯 Supabase查询模式（复制这些！）

from api_toolkit.services.supabase.api import SupabaseAPI
from api_toolkit.services.supabase.query_helpers import QueryBuilder

# PATTERN 1: Always explore first
api = SupabaseAPI('project1')
api.explore()  # See what tables exist
api.explore('leads')  # See columns and sample data

# PATTERN 2: Use QueryBuilder for complex queries
query = (QueryBuilder('leads')
         .where('score', '>=', 80)
         .where('status', '=', 'new')
         .contains('email', 'gmail')
         .order('score', desc=True)
         .limit(20))

hot_leads = query.execute(api)

# PATTERN 3: Check schema before querying
schema = api.get_schema('brands')
columns = [col['column'] for col in schema]
if 'industry' in columns:
    brands = api.query('brands', filters={'industry': 'eq.fashion'})

# PATTERN 4: Use documented patterns
from api_toolkit.services.supabase.table_docs import get_table_info

info = get_table_info('project1', 'leads')
print(info['sample_queries'])  # Copy working queries!

# PATTERN 5: Handle errors gracefully
try:
    data = api.query('users', limit=10)
except Exception as e:
    print(f"Query failed: {e}")
    # Check schema or use api.explore()

📋 筛选器操作参考

# COMPLETE FILTER SYNTAX GUIDE
filters = {
    # Comparison
    'age': 'eq.25',           # age = 25
    'status': 'neq.deleted',  # status != 'deleted'
    'score': 'gt.80',         # score > 80
    'score': 'gte.80',        # score >= 80
    'price': 'lt.100',        # price =', 18)
         .contains('email', 'gmail')
         .order('created_at', desc=True)
         .limit(10))

# ❌ BAD - Manual filter formatting
api.query('users', filters={'age': 'gte.18', 'email': 'ilike.%gmail%'})

3. 检查表文件

# ✅ GOOD - Use known patterns
from api_toolkit.services.supabase.table_docs import get_table_info

info = get_table_info('project1', 'leads')
example_query = info['sample_queries'][0]  # Use working examples

# ❌ BAD - Writing queries from scratch every time

4. 优雅地处理错误

# ✅ GOOD - Prepared for issues
try:
    api = SupabaseAPI('project1')
    if not api.test_connection():
        print("Connection issue - check .env")
        return
    
    data = api.query('leads', limit=10)
except Exception as e:
    print(f"Error: {e}")
    api.explore()  # Show what's available

# ❌ BAD - No error handling
data = api.query('leads')  # Crashes if anything goes wrong

5. 使用正确的项目名称

# ✅ GOOD - Clear and descriptive
api = SupabaseAPI('project1')    # Lead generation
api = SupabaseAPI('project2')  # CRM data
api = SupabaseAPI('project3')    # Web scraping

# ❌ BAD - Old aliases
api = SupabaseAPI('main')        # What is main?
api = SupabaseAPI('project2')    # Not descriptive

🔧 故障排除指南

问题：“表/列不存在”

# SOLUTION: Always check what actually exists
api = SupabaseAPI('project1')

# List all tables
api.explore()

# Check specific table schema
schema = api.get_schema('table_name')
for col in schema:
    print(f"{col['column']}: {col['type']}")

# Get sample data to see structure
sample = api.query('table_name', limit=3)
if sample:
    print(sample[0].keys())  # Shows all column names

问题：“连接失败”

# SOLUTION: Check environment step by step

# 1. Check if .env exists
ls -la .env api-toolkit/.env

# 2. Test specific project
python -c "
from api_toolkit.services.supabase.api import SupabaseAPI
api = SupabaseAPI('project1')
print('Connected!' if api.test_connection() else 'Failed!')
"

# 3. Check all projects
python api-toolkit/services/supabase/api.py test smoothed
python api-toolkit/services/supabase/api.py test blingsting
python api-toolkit/services/supabase/api.py test scraping

问题：“如何编写此查询？”

# SOLUTION: Use the examples and helpers

# 1. Check documented examples
from api_toolkit.services.supabase.table_docs import get_table_info
info = get_table_info('project1', 'leads')
print(info['sample_queries'])

# 2. Use QueryBuilder for complex queries
from api_toolkit.services.supabase.query_helpers import QueryBuilder
query = QueryBuilder('table').where('col', '=', 'value').build()
print(query)  # See the generated parameters

# 3. Reference working examples
python api-toolkit/services/supabase/examples.py smoothed

问题：“查询返回的数据太多”

# SOLUTION: Always use limits and pagination

# Check size first
count = api.count('large_table')
print(f"Total records: {count}")

# Get sample
sample = api.query('large_table', limit=10)

# Paginate through results
from api_toolkit.services.supabase.query_helpers import CommonQueries

for page in range(1, 5):  # First 4 pages
    params = CommonQueries.paginated('large_table', page=page, per_page=100)
    batch = api.query('large_table', **params)
    process_batch(batch)

环境变量

📍 将.env文件放在哪里

建议： 一 .env 文件在您的 项目根目录 （不在api工具包子目录中）。

your-project/
├── .env                    # ✅ PUT YOUR API KEYS HERE
├── api-toolkit/           # Symlink to toolkit
├── src/
└── main.py

它是如何工作的： 该工具包使用具有以下优先级的智能环境加载：

1. 项目根目录 (./env)-先检查✅
2. Toolkit目录(api-toolkit/.env)-后退
3. 主页目录(~/.api-toolkit.env)-全球回退

调试加载了哪个.env：

from api_toolkit.core.config import Config
print(f"Loaded env from: {Config.get_env_source()}")

所需的环境变量

在项目的 .env 文件：

Supabase项目

API密钥迁移（2026年夏季）： Supabase正在日落 service_role JWT键，并将其替换为 sb_secret_... 格式键。这两种格式在过渡期都有效。看 主管API关键讨论.

# Project 1: Smoothed (Lead Generation)
SUPABASE_URL=https://your-project-1.supabase.co
SUPABASE_SERVICE_ROLE_KEY=your-key-here  # sb_secret_... or legacy eyJ...

# Project 2: Blingsting (CRM)
SUPABASE_URL_2=https://your-project-2.supabase.co
SUPABASE_SERVICE_ROLE_KEY_2=your-key-here

# Project 3: Scraping (Web Scraping)
SUPABASE_URL_3=https://your-project-3.supabase.co
SUPABASE_SERVICE_ROLE_KEY_3=your-key-here

# Project 4: Thordata
SUPABASE_URL_4=https://your-project-4.supabase.co
SUPABASE_SERVICE_ROLE_KEY_4=your-key-here

# Direct Postgres URLs (for PostgresAPI / DDL operations)
SMOOTHED_SUPABASE_POSTGRES_URL=postgresql://...
BLINGSTING_SUPABASE_POSTGRES_URL=postgresql://...
SCRAPING_SUPABASE_POSTGRES_URL=postgresql://...
THORDATA_SUPABASE_POSTGRES_URL=postgresql://...

Context7（实时文档）

# Get your API key from https://context7.com
CONTEXT7_API_KEY=your-api-key-here
CONTEXT7_URL=https://context7.com/api/v1  # Optional, uses default

代谢物（分析）

METABASE_URL=http://localhost:3000  # Or your Metabase instance URL
METABASE_USERNAME=your-email@example.com
METABASE_PASSWORD=your-password
# Or use API key instead:
METABASE_API_KEY=mb_your_api_key_here

Smartlead（冷邮件）

SMARTLEAD_API_KEY=your-api-key-here
SMARTLEAD_WEBHOOK_SECRET=your-webhook-secret  # Optional, for webhook validation

渲染（云部署）

RENDER_API_KEY=your-api-key-here

BrightData（Web项目3和代理）

BRIGHTDATA_API_KEY=your-api-key-here
BRIGHTDATA_CUSTOMER_ID=your-customer-id

其他服务（待定）

# Klaviyo (Email Marketing)
KLAVIYO_API_KEY=pk_your_key_here

# Shopify (E-commerce)
SHOPIFY_ACCESS_TOKEN=your-token-here
SHOPIFY_STORE_URL=your-store.myshopify.com

快速设置检查

# Check which services are configured
python toolkit.py list

# Test individual service connections
python toolkit.py supabase test
python toolkit.py context7 test
python toolkit.py metabase test
python toolkit.py smartlead test
python toolkit.py render test
python toolkit.py brightdata test

# Check environment variables for a service
python toolkit.py supabase check
python toolkit.py context7 check

贡献

要添加新服务，请执行以下操作：

1. 在中使用模板 services/_template
2. 专注于你的用例，而不是完全覆盖
3. 将文档保存在1000个令牌以下
4. 使用真实工作流进行测试

未来的增强功能

• \[\]所有服务的批处理操作
• \[\]异步支持并行调用
• \[\]根据使用情况自动生成文档
• \[\]将模式导出为文档
• \[\]用于配置的Web UI

______________________________________________________________________

记住：每个保存的令牌都有更多的实际工作空间。停止加载90000个MCP开销令牌！