N1 Kh1 Lt0 X1 N MCP

自由职业MCP服务器-安装和使用指南

一个全面的自由职业平台聚合器MCP服务器，帮助用户使用人工智能找到演出、生成提案、协商价格并优化他们的自由职业档案

📖 文档快速链接

• 快速引用.md -快速命令和工具参考
• 验证_状态.md -测试结果和生产状态
• DEBUG_REPORT.md -Bug修复和调试摘要
• 结构.md -项目组织和文件结构
• 最终总结.md -完整调试总结

🚀 Claude桌面用户快速入门

想立即将其与Claude Desktop一起使用吗？遵循以下3个步骤：

1. 获取GREQ API密钥 （免费）：参观 console.groq.com，注册并创建API密钥

1. 添加到Claude桌面配置 -编辑您的 claude_desktop_config.json:

- 视窗: %APPDATA%\Claude\claude_desktop_config.json - 苹果电脑: ~/Library/Application Support/Claude/claude_desktop_config.json

将此添加到 mcpServers 部分（用你的替换路径和键）：

   {
     "mcpServers": {
       "freelance": {
         "command": "uv",
         "args": [
           "run",
           "--with", "mcp",
           "--with", "python-dotenv",
           "--with", "langchain-groq",
           "--with", "pydantic",
           "C:\\path\\to\\your\\freelance_server.py",
           "stdio"
         ],
         "env": {
           "GROQ_API_KEY": "gsk_your_key_here",
           "OWNER_COUNTRY_CODE": "1",
           "OWNER_PHONE_NUMBER": "5551234567"
         }
       }
     }
   }

1. 重新启动克劳德桌面 并开始使用以下命令：

- “搜索1000美元以下的Python演出” - “向我展示自由职业者市场趋势” - “为gig upwork_001生成提案”

需要更详细的说明吗？ 看 与Claude Desktop集成 在......下面

______________________________________________________________________

文件结构

mcp-server-1/
├── freelance_server.py          # Main MCP server (run this!)
├── requirements.txt             # Dependencies
├── .env.example                 # Environment template
├── README.md                    # This file
├── STRUCTURE.md                 # Detailed structure guide
│
├── core/                        # Core modules
├── database/                    # Database layer
├── mcp_extensions/              # MCP protocol extensions
├── utils/                       # Utilities
│
├── tests/                       # Test suite
├── examples/                    # Example code
├── docs/                        # Documentation
│
└── .github/                     # GitHub templates & workflows

看 结构.md 获取完整的目录文档。

快速开始

1.先决条件

• Python 3.8或更高版本
• pip包管理器
• Git（可选，用于克隆存储库）

2.安装

# Install required dependencies
uv pip install -r requirements.txt

# Or install individual packages
uv pip install mcp langchain-groq pydantic python-dotenv

3.环境设置

创建一个 .env 使用API密钥在项目目录中的文件：

# Windows
echo GROQ_API_KEY=your_actual_key_here > .env
echo OWNER_COUNTRY_CODE=1 >> .env
echo OWNER_PHONE_NUMBER=5551234567 >> .env

# Linux/Mac
cat > .env > .env

2.“未找到freelance_server.py”错误

# Make sure the server file is in the same directory
ls -la freelance_server.py
# Or adjust the path in freelance_client.py

3.模块导入错误

# Install missing dependencies
pip install -r requirements.txt
# Or check what's missing
python freelance_client.py --check-env

4.服务器连接问题

# Make sure server file is executable
python freelance_server.py stdio  # Test server directly
# Check for syntax errors in server file
python -m py_compile freelance_server.py

调试模式

通过设置环境变量启用详细日志记录：

export MCP_DEBUG=1
python freelance_client.py --mode demo

手动服务器测试

独立测试服务器：

# Run server in stdio mode
python freelance_server.py stdio

# Run server with SSE transport
python freelance_server.py sse

# Run server with HTTP transport
python freelance_server.py streamable-http

高级用法

自定义配置

修改 freelance_client.py 自定义：

• 服务器连接参数
• 演示场景和数据
• 错误处理行为
• 输出格式化

与Claude Desktop集成（推荐）

步骤1：创建环境文件

创建一个 .env 项目目录中的文件：

# Windows
copy NUL .env

# Linux/Mac
touch .env

将API密钥添加到 .env:

GROQ_API_KEY=your_groq_api_key_here
MCP_AUTH_TOKEN=your_optional_auth_token
OWNER_COUNTRY_CODE=1
OWNER_PHONE_NUMBER=5551234567

步骤2：获取GROQ API密钥

1. 访问 Groq控制台
2. 注册或登录
3. 导航到API密钥部分
4. 创建新的API密钥
5. 复制并粘贴到您的 .env 文件

步骤3：找到Claude桌面配置

• 视窗: %APPDATA%\Claude\claude_desktop_config.json
• 苹果电脑: ~/Library/Application Support/Claude/claude_desktop_config.json
• Linux: ~/.config/Claude/claude_desktop_config.json

步骤4：更新Claude桌面配置

打开 claude_desktop_config.json 并添加自由服务器配置：

{
  "mcpServers": {
    "freelance": {
      "command": "uv",
      "args": [
        "run",
        "--with", "mcp",
        "--with", "python-dotenv",
        "--with", "langchain-groq",
        "--with", "pydantic",
        "/absolute/path/to/your/freelance_server.py",
        "stdio"
      ],
       "env": {
         "GROQ_API_KEY": "your_groq_api_key_here",
         "MCP_AUTH_TOKEN": "your_optional_auth_token",
         "OWNER_COUNTRY_CODE": "1",
         "OWNER_PHONE_NUMBER": "5551234567"
       }
    }
  }
}

重要提示：

• 替换 /absolute/path/to/your/freelance_server.py 与您的实际完整路径 freelance_server.py 文件
• 在Windows上，使用双反斜杠： C:\\Users\\YourName\\MCPs\\freelance_server.py
• 在Mac/Linux上，使用正斜杠： /Users/YourName/MCPs/freelance_server.py
• 将所有占位符值替换为您的实际API密钥和电话号码

Windows示例：

{
  "mcpServers": {
    "freelance": {
      "command": "C:\\Users\\YourName\\.local\\bin\\uv.EXE",
      "args": [
        "run",
        "--with", "mcp",
        "--with", "python-dotenv",
        "--with", "langchain-groq",
        "--with", "pydantic",
        "C:\\Users\\YourName\\MCPs\\mcp-server-1\\freelance_server.py",
        "stdio"
      ],
      "env": {
         "GROQ_API_KEY": "gsk_xxxxxxxxxxxxxxxxxxxxx",
         "MCP_AUTH_TOKEN": "your_optional_auth_token",
         "OWNER_COUNTRY_CODE": "1",
         "OWNER_PHONE_NUMBER": "5551234567"
      }
    }
  }
}

步骤5：重新启动克劳德桌面

1. 完全退出Claude Desktop（不仅仅是关闭窗口）
2. 重新打开克劳德桌面
3. 自由服务器现在应该可用

步骤6：验证安装

在Claude Desktop中，尝试询问：

• “搜索500美元以下的Python自由职业者”
• “向我展示当前的自由职业市场趋势”
• “验证所有者电话号码”

克劳德桌面集成故障排除：

1. 服务器显示为“失败”：

- 检查日志：从错误中打开“打开日志文件夹” - 寻找 ModuleNotFoundError -意味着缺少依赖项 - 全部验证 --with 包包含在args中

1. “服务器已断开连接”错误：

- 确保 stdio 是args数组中的最后一个参数 - 检查以下路径 freelance_server.py 绝对正确 - 验证 uv 已安装：运行 uv --version 在终端

1. 未加载环境变量：

- 仔细检查 .env 文件与存在于同一目录中 freelance_server.py - 验证中的环境值 claude_desktop_config.json 匹配你的 .env 文件 - 确保没有额外的引号或空格

1. 查找uv路径（Windows）：

   where.exe uv

1. 查找uv路径（Mac/Linux）：

   which uv

替代方案：手动安装方法

如果您更喜欢全局安装依赖项而不是使用 --with 旗帜：

# Install dependencies globally with uv
uv pip install mcp python-dotenv langchain-groq pydantic

# Then use simpler config
{
  "mcpServers": {
    "freelance": {
      "command": "uv",
      "args": [
        "run",
        "/path/to/freelance_server.py",
        "stdio"
      ],
      "env": {
        "GROQ_API_KEY": "your_key_here",
        "OWNER_COUNTRY_CODE": "1",
        "OWNER_PHONE_NUMBER": "5551234567"
      }
    }
  }
}

与ngrok集成以实现远程访问

如果您想通过HTTPS远程访问MCP服务器：

# 1. Download and install ngrok
# Visit: https://ngrok.com/download

# 2. Add your authtoken (sign up at ngrok.com to get one)
ngrok config add-authtoken 

# 3. Start your MCP server on a specific port
python freelance_server.py sse --port 8080

# 4. In another terminal, expose it with ngrok
ngrok http 8080

# 5. Use the provided HTTPS URL to connect remotely
# Example: https://abc123.ngrok.io

注： 对于生产使用，考虑实施适当的身份验证和安全措施。

API扩展

客户端可以扩展到：

• 连接到实时自由平台API
• 与本地数据库集成
• 添加自定义分析工具
• 支持其他LLM提供商

业绩说明

• 由于服务器启动，首次运行可能会变慢
• LLM调用需要互联网连接和API信用
• 代码审查流程文件高达50MB
• 支持并发gig搜索
• 服务器为演示维护内存缓存

安全考虑

• API键仅从环境变量加载
• 文件操作被沙盒化到当前目录
• 未记录敏感数据
• 服务器在独立进程中运行
• 备份文件包括安全时间戳

可用的MCP工具

一旦与Claude Desktop集成，您将可以访问这些工具：

🔍 搜索与发现

• search_gigs -按技能、预算、项目类型和平台搜索自由职业演出
• validate -验证服务器所有者的电话号码

👤 配置文件管理

• create_user_profile -创建一个新的自由职业者档案，包括技能和费率
• analyze_profile_fit -分析个人资料与特定工作的匹配程度
• optimize_profile -获取基于AI的配置文件优化建议

📝 提案与谈判

• generate_proposal -使用AI生成个性化提案
• negotiate_rate -获取费率协商策略和消息

💻 代码工具

• code_review -使用度量和建议审查代码质量
• code_debug -调试并自动修复代码问题

📊 追踪

• track_application_status -跟踪和分析应用程序性能

📚 资源

• freelance://profile/{profile_id} -访问用户配置文件数据
• freelance://gigs/{platform} -从特定平台获得演出
• freelance://market-trends -查看当前市场趋势和见解

贡献

欢迎投稿！请随时提交拉取请求。

许可证

这个项目是开源的，可以在MIT许可证下使用。

支持

有关问题、疑问或贡献，请访问 .