MCP 服务器示例

Model Context Protocol (MCP) 服务器示例，具有简化且集中的工具集。此仓库包含用于 Obsidian 保险库管理和浏览器自动化的实际工作示例。

状态：

• Obsidian 示例：生产就绪 ✅
• AWS 浏览器示例：与真实 AWS Agent Core 集成的生产就绪 ✅
• Playwright 浏览器示例：生产就绪 ✅

🚀 快速开始

1. 克隆并设置

   git clone <repository-url>
   cd mcp_server_examples
   make setup-all  # 安装依赖并构建所有示例
   

2. 配置你的 MCP 客户端 使用 run.sh 文件作为入口点

   • 每个示例都有一个 run.sh 文件，它会自动处理虚拟环境
   • 在你的 MCP 客户端配置中使用这些 .sh 文件的绝对路径

3. 测试你的设置 使用以下命令

📁 可用服务器

Obsidian 保险库管理

• Python (FastMCP)：examples/obsidian_python/run.sh
• TypeScript (官方 SDK)：examples/obsidian_typescript/run.sh

工具： list, read, create, update, move, search, delete

浏览器自动化

• Python (FastMCP + AWS Agent Core)：examples/aws_agent_core_browser_python/run.sh
• TypeScript (AWS Agent Core)：examples/aws_agent_core_browser_typescript/run.sh

工具： fetch, screenshot

⚙️ 设置说明

Obsidian 服务器

先决条件

• 已配置 LiveSync 插件的 Obsidian
• 运行中的 CouchDB 服务器（本地或远程）

Python 设置

cd examples/obsidian_python
pip install -r requirements.txt

# 设置环境变量
export VAULT_BASE_URL="http://localhost:5984"
export VAULT_DB_NAME="your-obsidian-vault"
export VAULT_USERNAME="your-username"  # 可选
export VAULT_PASSWORD="your-password"  # 可选

TypeScript 设置

cd examples/obsidian_typescript
npm install
npm run build

# 设置与 Python 相同的环境变量

浏览器服务器

Python (AWS Agent Core)

cd examples/aws_agent_core_browser_python
pip install -r requirements.txt

# 可选的 AWS 配置
export AWS_PROFILE="your-profile"
export AWS_REGION="us-west-2"

TypeScript (AWS Agent Core)

cd examples/aws_agent_core_browser_typescript
npm install
npx playwright install chromium
npm run build

🔧 客户端配置

Claude Desktop

添加到你的 claude_desktop_config.json：

{
  "mcpServers": {
    "obsidian-python": {
      "command": "/absolute/path/to/examples/obsidian_python/run.sh",
      "env": {
        "VAULT_BASE_URL": "http://localhost:5984",
        "VAULT_DB_NAME": "your-vault-name",
        "VAULT_USERNAME": "your-username",
        "VAULT_PASSWORD": "your-password"
      }
    },
    "aws-browser": {
      你的配置
    }
  }
}

Continue.dev

添加到你的 config.json：

{
  "mcpServers": [
    {
      "name": "obsidian-python",
      "command": ["/absolute/path/to/examples/obsidian_python/run.sh"],
      "env": {
        "VAULT_BASE_URL": "http://localhost:5984",
        "VAULT_DB_NAME": "your-vault-name",
        "VAULT_USERNAME": "your-username",
        "VAULT_PASSWORD": "your-password"
      }
    },
    {
      "name": "aws-browser",
      "command": ["/absolute/path/to/examples/aws_agent_core_browser_typescript/run.sh"],
      "env": {}
    }
  ]
}

MCP Inspector (开发)

npx @modelcontextprotocol/inspector examples/obsidian_python/run.sh

📋 Makefile 命令

使用提供的 Makefile 进行简单的路径管理：

make show-paths          # 显示所有绝对路径
make claude-config       # 生成 Claude Desktop 配置
make continue-config     # 生成 Continue.dev 配置
make test-obsidian-py    # 测试 Obsidian Python 服务器
make test-browser-ts     # 测试 TypeScript 浏览器服务器

🔍 测试你的设置

快速测试命令

# 测试 Obsidian Python 服务器
echo '{"method": "tools/list"}' | examples/obsidian_python/run.sh

# 测试 AWS 浏览器 TypeScript 服务器
echo '{"method": "tools/list"}' | examples/aws_agent_core_browser_typescript/run.sh

使用 MCP Inspector

# 交互式测试界面
npx @modelcontextprotocol/inspector examples/obsidian_python/run.sh

🌟 示例用法

Obsidian 保险库操作

# 列出所有文件
list()

# 读取特定笔记
read("daily/2024-01-15.md")

# 创建新笔记
create("ideas/new-project.md", "# 新项目\n\n好主意！")

# 搜索文件
search("*.md")

浏览器自动化

# 获取网页内容
fetch("https://example.com")

# 截图
screenshot("https://github.com")

🔧 环境变量

Obsidian 服务器

变量	描述	是否必需
VAULT_BASE_URL	CouchDB 服务器 URL	是
VAULT_DB_NAME	数据库/保险库名称	是
VAULT_USERNAME	认证用户名	否
VAULT_PASSWORD	认证密码	否

浏览器服务器

变量	描述	默认值
AWS_PROFILE	AWS 配置文件名	无
AWS_REGION	AWS 区域	us-west-2

🏗️ 架构

入口点

• .sh 文件：所有示例都使用 run.sh 作为入口点
• 虚拟环境：Shell 脚本会自动激活 Python venv 并处理依赖项
• 路径独立性：无需手动管理 Python/Node 路径

清晰的工具设计

• Obsidian：7 个核心文件操作（CRUD + 搜索/移动）
• 浏览器：2 个专注的工具（获取内容 + 截图）

框架选择

• Python：FastMCP 提供干净的基于装饰器的 API
• TypeScript：官方 MCP SDK 以实现最大兼容性

错误处理

• 综合错误捕获和用户友好的消息
• 自动连接管理和重试
• 平滑回退（例如，当 AWS Agent Core 不可用时使用 Playwright）

📚 单独的 README

每个示例目录都包含详细的文档：

• examples/obsidian_python/README.md
• examples/obsidian_typescript/README.md
• examples/aws_agent_core_browser_python/README.md
• examples/aws_agent_core_browser_typescript/README.md

🤝 贡献

1. 分叉仓库
2. 创建你的功能分支
3. 遵循现有的代码风格和架构
4. 添加测试和文档
5. 提交拉取请求

📄 许可证

MIT 许可证 - 查看各个示例目录以获取实现细节。