AI导哈

MCP服务器

一个全面的MCP服务器，为Claude Desktop和其他MCP客户端提供内存管理、工作区文件I/O、天气数据和实用工具。

  • by TobiSan5
  • Python
  • 本地部署
  • 1 星标
  • 更新于
在 GitHub 查看 TobiSan5/first-mcp

使用说明

第一台MCP服务器

适用于Claude Desktop和其他MCP客户端的综合MCP服务器，具有内存管理、工作区文件I/O、天气数据和实用工具等功能。

🚀 v1.1.0的新增功能

界面简化：将工具从52个减少到32个（选项减少38%），同时保留所有基本功能。 阅读完整的发行说明

主要改进：

  • ✅ 精简的工具集，专注于核心功能
  • ✅ 具有适当委托模式的增强架构
  • ✅ 改进的测试基础设施
  • ✅ 更清晰的代码库带来更好的开发体验

🎯 面向最终用户

快速安装

# Install directly from GitHub (recommended)
pip install git+https://github.com/TobiSan5/first-mcp.git

# Or clone and install locally
git clone https://github.com/TobiSan5/first-mcp.git && cd first-mcp && pip install -e .

基本设置

  1. 设置环境变量 （为您的数据创建目录）：

    # Windows
setx FIRST_MCP_DATA_PATH "%APPDATA%\FirstMCP"
setx FIRST_MCP_WORKSPACE_PATH "%USERPROFILE%\Documents\ClaudeWorkspace"

# macOS/Linux  
export FIRST_MCP_DATA_PATH="$HOME/.local/share/FirstMCP"
export FIRST_MCP_WORKSPACE_PATH="$HOME/Documents/ClaudeWorkspace"

  2. 配置您的MCP客户端 （克劳德桌面示例）：

    {
  "mcpServers": {
    "first-mcp": {
      "command": "first-mcp",
      "env": {
        "FIRST_MCP_DATA_PATH": "/path/to/your/data",
        "FIRST_MCP_WORKSPACE_PATH": "/path/to/your/workspace"
      }
    }
  }
}

  3. 重新启动MCP客户端 开始使用这些工具！

所得

核心工具（共32个）:

  • 内存管理：跨会话存储、搜索和组织信息
  • 文件工作区：带有标记和元数据的持久文件存储
  • 天气数据：位置查询和天气预报
  • 计算器：安全的数学表达式和时差
  • 数据库操作：通用TinyDB数据库管理
  • 系统实用程序：文件列表、文本分析、日历、系统信息

在Claude中尝试以下命令：

  • “存储此重要信息：[您的笔记]”
  • “在我的记忆中搜索python项目”
  • “你们有什么工具？”
  • “获取挪威奥斯陆的天气”
  • “计算：2^10+24”
  • “将此代码段存储在文件中”

🛠️ 适用于开发人员和适配器

架构概述

该软件包遵循干净的3层架构：

MCP Layer (server_impl.py)
├─ Tool registration and MCP protocol handling  
├─ Server timestamps and error formatting
└─ Parameter validation

Server Logic Layer
├─ Business rules and validation
├─ Response formatting  
└─ Environment configuration

Data Processing Layer (memory/, fileio/, etc.)  
├─ Pure data manipulation functions
├─ Database operations
└─ External API integrations

集成的主要功能

  • 模块化设计：存储系统提取为可重复使用的包(src/first_mcp/memory/)
  • 清洁进口：所有组件均可通过显式导入获得
  • 基于环境的配置：对所有路径和API键使用环境变量
  • 综合测试：三层测试结构（MCP协议、数据层、智能层）
  • 向后兼容：从以前的版本升级是安全的

开发设置

# Clone and set up development environment
git clone https://github.com/TobiSan5/first-mcp.git
cd first-mcp
pip install -e .

# Run tests
python tests/server_implementation/test_mcp_client.py

# Run in debug mode
python -m first_mcp.server --debug

添加新工具

只需添加功能 @mcp.tool() 装饰师 src/first_mcp/server_impl.py:

@mcp.tool()
def my_custom_tool(input_text: str) -> Dict[str, Any]:
    """
    Your tool description here.
    
    Args:
        input_text: Description of parameter
        
    Returns:
        Dictionary with results
    """
    result = {"processed": input_text.upper()}
    return add_server_timestamp(result)  # Include server timestamp

📚 文档

🌐 MCP生态系统

此服务器适用于任何 模型上下文协议（MCP） 兼容应用程序：

  • 克劳德桌面 -主要目标
  • 光标 -IDE集成
  • 带有MCP扩展的VS代码 -发展环境
  • 任何MCP客户端 -符合协议的应用程序

🔧 环境变量（可选）

# API Keys (for weather functionality)
export OPENWEATHERMAPORG_API_KEY="your_key_here"  
export GOOGLE_API_KEY="your_key_here"

# Data Storage (defaults to current directory if not set)
export FIRST_MCP_DATA_PATH="/custom/data/path"
export FIRST_MCP_WORKSPACE_PATH="/custom/workspace/path"

🐛 故障排除

常见问题：

  1. “找不到工具” → 验证MCP客户端配置并重新启动客户端
  2. “导入错误” → 确保包安装在正确的Python环境中
  3. “权限被拒绝” → 检查数据/工作区目录是否存在并且可写
  4. “没有这样的文件” → Run first-mcp --debug 检查设置

调试模式：

python -m first_mcp.server --debug

📈 版本历史记录

  • v1.1.0版本 （2025-09-05）：界面优化-减少52→32 工具、架构改进
  • v1.0.0：具有完整功能集的初始版本

许可证：MIT| 作者：托尔比约恩·维克斯塔德| 仓库: github/TobiSan5/第一mcp

相关 MCP