MCP Theanswer

报价保险库MCP服务器

用于管理和检索励志名言的模型上下文协议（MCP）服务器。作为现代Python开发实践和MCP集成的演示而构建。

这是什么？

Quote Vault是一个MCP服务器，它使AI助手（如Claude）能够管理个人报价集合。它提供：

• 工具：添加、搜索、更新和删除引号
• 资源：通过URI对报价集合进行只读访问
• 提示词：寻找灵感和分析引文的指导模板

该服务器预装了Douglas Adams的语录，但适用于您构建的任何集合。

什么是MCP？

模型上下文协议（MCP） 是将AI模型连接到外部工具和数据源的标准。MCP服务器公开了三种类型的原语：

• 工具：AI可以调用的功能（例如。， add_quote, search_quotes)
• 资源：AI可以通过URI读取的数据（例如。， quote://random)
• 提示词：指导AI行为的模板（例如。， find-inspiration)

此服务器适用于任何MCP客户端，包括 克劳德桌面.

特性

• 完整的CRUD操作：添加、搜索、更新和删除引号
• 灵活搜索：按文本、作者或标签查找引文
• 标签管理：用多个标签组织报价
• 随机报价：通过随机选择报价获得灵感
• 元数据：存储每个报价的来源、年份和上下文
• SQLite数据库：具有全文搜索功能的可靠本地存储
• 开发工具：用于在没有Claude Desktop的情况下进行测试的CLI测试客户端
• 预种子数据：20+道格拉斯·亚当斯语录开头

安装

这个项目需要Python 3.11+，并使用 紫外线 用于依赖性管理。

快速安装

# Install uv if you don't have it
curl -LsSf https://astral.sh/uv/install.sh | sh

# Clone the repository
git clone https://github.com/yourusername/mcp-theanswer.git
cd mcp-theanswer

# Install dependencies
uv sync

# Optional: Seed the database with Douglas Adams quotes
export QUOTE_VAULT_AUTO_SEED=true
uv run python -m mcp_theanswer.server

使用Claude Desktop进行设置

要将Quote Vault与Claude Desktop一起使用，请执行以下操作：

1. 安装服务器 （见上文）

1. 配置Claude桌面 通过编辑配置文件：

- macOS: ~/Library/Application Support/Claude/claude_desktop_config.json - 视窗: %APPDATA%\Claude\claude_desktop_config.json

1. 添加服务器配置:

{
  "mcpServers": {
    "quote-vault": {
      "command": "uv",
      "args": [
        "run",
        "--frozen",
        "--directory",
        "/absolute/path/to/mcp-theanswer",
        "python",
        "-m",
        "mcp_theanswer.server"
      ],
      "env": {
        "QUOTE_VAULT_AUTO_SEED": "true"
      }
    }
  }
}

1. 重新启动克劳德桌面

1. 验证 通过问克劳德：“你有什么工具可以使用？”你应该看到列出的与报价相关的工具。

环境变量

• QUOTE_VAULT_DB_PATH：数据库文件路径（默认值： ~/.local/share/quote-vault/quotes.db)
• QUOTE_VAULT_AUTO_SEED：使用Douglas Adams引号自动播种（默认值： false)
• QUOTE_VAULT_LOG_LEVEL：日志记录级别（默认值： INFO)

用法

使用克劳德桌面

配置后，您可以自然地与报价进行交互：

You: "Add this quote: 'The Answer is 42' by Deep Thought"
Claude: [Uses add_quote tool to save it]

You: "Find me some inspiring quotes about life"
Claude: [Uses search_quotes tool and presents results]

You: "Give me a random quote"
Claude: [Uses quote://random resource or random_quote tool]

可用工具

可用资源

可用提示

发展

开发测试客户端

使用附带的CLI客户端在没有Claude Desktop的情况下测试MCP服务器：

# List all available tools
python scripts/test_client.py list-tools

# List all resources
python scripts/test_client.py list-resources

# List all prompts
python scripts/test_client.py list-prompts

# Add a quote
python scripts/test_client.py tool add_quote '{
  "text": "The Answer is 42",
  "author": "Deep Thought",
  "tags": ["humor", "philosophy"]
}'

# Search for quotes
python scripts/test_client.py tool search_quotes '{
  "query": "life",
  "author": "Douglas Adams"
}'

# Get a random quote
python scripts/test_client.py resource quote://random

# Get collection statistics
python scripts/test_client.py resource quote://stats

# Use a prompt
python scripts/test_client.py prompt find-inspiration '{
  "situation": "feeling overwhelmed"
}'

运行测试

# Run all tests with coverage (89% coverage)
uv run --frozen pytest

# Run specific test file
uv run --frozen pytest tests/test_tools.py

# Run with verbose output
uv run --frozen pytest -v

# Generate HTML coverage report
uv run --frozen pytest --cov-report=html

代码质量

# Format code with ruff
uv run --frozen ruff format .

# Lint code
uv run --frozen ruff check .

# Fix linting issues automatically
uv run --frozen ruff check . --fix

# Type check with pyright
uv run --frozen pyright

# Run all pre-commit hooks
uv run pre-commit run --all-files

项目结构

mcp-theanswer/
├── src/mcp_theanswer/
│   ├── __init__.py
│   ├── main.py                 # Legacy CLI (returns 42)
│   ├── server.py               # MCP server entry point
│   ├── config.py               # Environment configuration
│   ├── seed_data.py            # Douglas Adams quotes seed data
│   ├── database/
│   │   ├── models.py           # Quote and Tag data models
│   │   ├── operations.py       # Database CRUD operations
│   │   └── schema.py           # SQLite schema and migrations
│   └── mcp/
│       ├── tools.py            # MCP tool implementations
│       ├── resources.py        # MCP resource implementations
│       └── prompts.py          # MCP prompt templates
├── scripts/
│   └── test_client.py          # Development test client
├── tests/
│   ├── test_database.py        # Database operation tests
│   ├── test_tools.py           # MCP tool tests
│   ├── test_resources.py       # MCP resource tests
│   ├── test_prompts.py         # MCP prompt tests
│   ├── test_schema.py          # Database schema tests
│   ├── test_seed_data.py       # Seed data tests
│   └── test_server.py          # Server initialization tests
├── DESIGN.md                   # Detailed design document
├── IMPLEMENTATION.md           # Implementation phases and plan
├── CLAUDE.md                   # Claude Code development guide
├── pyproject.toml              # Project configuration
└── README.md                   # This file

建筑

Quote Vault MCP服务器是分层构建的：

1. 数据库层 (database/)：带Quote和Tag模型的SQLite数据库
2. MCP层 (mcp/)：工具、资源和提示实现
3. 服务器层 (server.py)：MCP服务器初始化和stdio传输
4. 配置 (config.py)：基于环境的配置

服务器使用：

• SQLite 用于可靠的本地存储
• MCP Python SDK 用于协议实施
• stdio传输 用于与MCP客户端通信
• 异步/等待 用于非阻塞操作

数据库模式

引号 表：

• id：整数主键
• text：报价文本（必填）
• author：作者姓名（必填）
• source：来源/书籍/背景（可选）
• year：出版年份（可选）
• created_at：时间戳

标签 表：

• id：整数主键
• name：标签名称（唯一）

quote_tags 连接表：

• 将引号链接到标签（多对多）
• 删除报价时级联删除

故障排除

Claude Desktop看不到服务器

1. 检查配置文件路径是否正确
2. 验证项目的绝对路径是否正确
3. 完全重新启动克劳德桌面
4. 查看Claude Desktop的日志： ~/Library/Logs/Claude/ （macOS）

数据库未播种

1. 确保 QUOTE_VAULT_AUTO_SEED=true 设置在环境中
2. 检查数据库文件权限
3. 验证数据库尚未播种（种子只运行一次）
4. 检查服务器日志是否有错误

测试客户端无法连接

1. 验证您是从项目根目录运行的
2. 检查一下 uv 已安装并位于PATH中
3. 确保安装了依赖项： uv sync

贡献

欢迎投稿！拜托：

1. 分叉存储库
2. 创建要素分支(git checkout -b feature/amazing-feature)
3. 通过测试进行更改
4. 运行测试和质量检查： uv run --frozen pytest && uv run --frozen ruff check .
5. 提交您的更改(git commit -m 'feat: add amazing feature')
6. 推到分支(git push origin feature/amazing-feature)
7. 打开拉取请求

未来的增强功能

对未来版本的想法（超出v1的范围）：

• 导入/导出（JSON、CSV、Markdown）
• 备份和恢复功能
• 带排名的全文搜索
• 报价集合/播放列表
• 将报价导出为图像
• 用于浏览的Web UI
• 喜爱/评分系统
• 面向终端用户的全功能CLI

许可证

该项目根据MIT许可证获得许可。

致谢

• 内置于 紫外线 用于快速依赖关系管理
• 用途 MCP Python SDK 用于协议实施
• 代码质量 颈毛
• 测试与 pytest
• 灵感来自道格拉斯·亚当斯和 _银河系漫游指南_

了解更多

• MCP文件
• MCP规范
• 克劳德桌面
• 设计文档 -详细的架构决策
• 实施指南 -分阶段开发计划