Python Fast MCP Watch List

监视列表MCP服务器

灯光、摄像头、自动化。

此项目使用以下代码实现了电影监视列表模型上下文协议（MCP）服务器 FastMCP。它为您提供了一种管理电影观看列表的干净方法，包括标记已观看/未观看的电影、添加评级、检索列表视图以及生成LLM驱动的摘要。

演示录制

观看实际项目：


特性

LLM采样

生成友好的、基于人工智能的观察名单摘要。这 summarize_watchlist 该工具使用LLM采样将您的电影列表发送到语言模型，并返回简短、有见地的摘要。它可以突出你收藏中的流派、趋势或有趣的模式。

• ENABLE_LLM_SAMPLING=true （默认）：通过MCP上下文使用LLM采样。
• ENABLE_LLM_SAMPLING=false：返回确定性局部概览，而不调用采样。

引出

在需要时收集额外的意见。示例：当将电影标记为已观看时，服务器可以使用启发流提示用户进行评分（满分10分）。此行为显示在 mark_watched.

• ENABLE_ELICITATION=true （默认）： mark_watched 通过启发要求评分。
• ENABLE_ELICITATION=false: mark_watched 期待直接 rating 争论。
• 在范围内强制执行评级验证 0-10.

数据库模式

服务器跨两个表存储数据：

• watchlists

- id (int，主键） - coolname (str，独特）

• watchlist

- watchlist_id (int，外键 watchlists.id) - title (str) - year (int) - watched (bool) - rating (float，可选，满分10）

工具是指使用 watchlist_key （生成的coolname）。

数据库连接

• 默认数据库：本地SQLite(watchlist.db)
• 通过支持远程数据库 DATABASE_URL （首选）和 DB_URL （备用别名）
• 优先级：如果两者都设置， DATABASE_URL 使用。
• 配置无效的URL会自动回退到本地SQLite。
• 支持的URL样式：

- postgresql://user:[REDACTED_SQL_PASSWORD_1]@host:5432/dbname - mysql://user:[REDACTED_SQL_PASSWORD_1]@host:3306/dbname - sqlite:///absolute/or/relative/path.db

工具

• create_watchlist() -> str -创建监视列表并返回生成的 watchlist_key.
• show_watchlist(watchlist_key: str) -将一个监视列表的条目以纯列表形式返回。
• add_movie(watchlist_key: str, title: str, year: int) -将电影添加到观看列表。
• mark_watched(...) -将电影标记为已观看（签名取决于 ENABLE_ELICITATION):

- mark_watched(watchlist_key: str, title: str) 当启发被启用时。 - mark_watched(watchlist_key: str, title: str, rating: float) 当启发功能被禁用时。

• unwatch_movie(watchlist_key: str, title: str) -将电影标记为未观看（删除评级）。
• delete_movie(watchlist_key: str, title: str) -从观看列表中删除电影。
• summarize_watchlist(...) -总结一份观察名单（签名取决于 ENABLE_LLM_SAMPLING):

- summarize_watchlist(watchlist_key: str, ctx) 当采样功能被激活时。 - summarize_watchlist(watchlist_key: str) 当采样被禁用时。

资源

• watchlist://{watchlist_key}/movie/{title} -按一个观看列表的标题获取电影的详细信息。
• watchlist://{watchlist_key}/all -获取一个观看列表中的所有电影。
• watchlist://{watchlist_key}/unwatched -为一个观看列表获取未观看的电影。
• watchlist://{watchlist_key}/watched -在一个观看列表中观看电影。

提示

• prompt_add_movie(title: str, year: int) -提示添加电影。
• prompt_unwatch_movie(title: str) -提示将电影标记为未观看。
• prompt_delete_movie(title: str) -提示删除电影。
• prompt_mark_watched(title: str) -提示将电影标记为已观看。
• prompt_show_watchlist() -提示显示您的完整电影观看列表。

大多数工具和资源返回带有标题、年份、观看状态和评级（如果可用）的格式化字符串。 show_watchlist(watchlist_key) 返回一个简单的电影字符串列表。在需要额外用户输入的情况下使用启发式。

运行时功能标志

在启动服务器之前设置这些：

# true (default) -> mark_watched(watchlist_key, title) uses elicitation flow
# false -> mark_watched(watchlist_key, title, rating) requires direct rating argument
export ENABLE_ELICITATION=true

# true (default) -> summarize_watchlist(watchlist_key, ctx) uses LLM sampling
# false -> summarize_watchlist(watchlist_key) returns deterministic local summary
export ENABLE_LLM_SAMPLING=true

需求

• Python：3.12或更高版本（请参阅 pyproject.toml)
• Node.js：MCP检查器需要（通过 npx).
• MCP CLI：作为依赖项自动安装(mcp[cli] 在 pyproject.toml)

入门指南

1.安装 紫外线

macOS：

brew install uv

窗户：

winget install --id=astral-sh.uv -e

有关其他平台，请参阅 紫外线文件.

2.安装依赖项

从安装依赖项 pyproject.toml, uv.lock，或 requirements.txt:

uv sync

3.以可编辑模式安装软件包

uv pip install -e .

4.从本地源安装/刷新CLI工具

如果您是在本地开发，请从此仓库安装CLI。使用 --force --no-cache 为了确保安装的工具始终反映您最新的本地代码（绕过uv的构建缓存）：

uv tool install --force --no-cache .

5.在本地运行服务器

通过模块运行：

python -m mcp_server_watchlist.server

或通过脚本入口点运行（从 pyproject.toml):

mcp-server-watchlist

要使用远程SQL数据库，请设置 DATABASE_URL 开始前：

export DATABASE_URL="postgresql://username:[REDACTED_SQL_PASSWORD_1]word@db-host:5432/watchlist"
mcp-server-watchlist

6.打开MCP检查器

在单独的终端中：

npx @modelcontextprotocol/inspector

注意：Inspector需要Node.js。看 MCP检查员文件.

端点和测试

MCP检查员

使用 MCP检查员 作为与工具、资源和提示交互的web界面。

如何使用MCP检查器：

1. 启动服务器和检查器（请参阅入门）。
2. 打开检查器UI（通常http://localhost:6274)并以交互方式调用工具、资源和提示。

健康检查端点

服务器提供轻量级的健康检查端点，以验证其是否正在运行并查看可用功能：

• /health -返回一个样式化的HTML仪表板，显示服务器状态、数据库连接以及所有可用的工具、提示和资源。在浏览器中访问 http://localhost:8000/health.
• /health/json -返回带状态的JSON(healthy 或 degraded)，数据库详细信息(database, database_connected)，以及完整的工具、提示和资源列表。可用于监控和自动检查。

如果数据库不可用，服务器仍会启动并报告运行状况恶化。

HTML健康页面与应用程序打包在一起，并从包资源加载，因此它在本地可编辑模式和安装的CLI模式下工作。

curl命令示例：

# HTML health dashboard
curl http://localhost:8000/health

# JSON API health check
curl http://localhost:8000/health/json | jq

______________________________________________________________________

VS代码MCP用户配置示例

根据您的设置，在VS Code用户/工作区设置中使用以下选项之一。

1.本地设置（运行自己的服务器）

按照入门中的所有步骤进行操作，然后使用：

{
  "servers": {
    "mcp-server-watchlist-local": {
      "url": "http://127.0.0.1:8000/mcp/",
      "type": "http"
    }
  },
  "inputs": []
}

2.直接使用（托管服务器，无需设置）

使用此配置连接到托管服务器：

{
  "servers": {
    "mcp-server-watchlist-remote": {
      "url": "https://python-fastmcp-watchlist.onrender.com/mcp/",
      "type": "http"
    }
  },
  "inputs": []
}

根据您是希望本地使用还是托管使用，仅使用相关配置。

______________________________________________________________________

故障排除和常见问题

CLI工具的安装和使用

您可以安装 mcp-server-watchlist CLI全球使用 紫外线.

从本地源安装（开发）

如果您在本地工作并希望使用当前的开发版本：

uv tool install --force --no-cache .

这将从您的本地目录安装，并刷新已安装的工具以包含您的最新更改。

全局安装（发布时从PyPI）

一旦发布：

uv tool install mcp-server-watchlist
# or for user only:
uv tool install --user mcp-server-watchlist

安装后：

mcp-server-watchlist

设置数据库URL

集 DATABASE_URL 在运行工具之前（或 DB_URL 作为备用别名）：

# Use SQLite (default, relative to current directory)
export DATABASE_URL="sqlite:///watchlist.db"
mcp-server-watchlist

# Use a specific absolute path for SQLite
export DATABASE_URL="sqlite:////absolute/path/to/watchlist.db"
mcp-server-watchlist

# Use PostgreSQL
export DATABASE_URL="postgresql://user:[REDACTED_SQL_PASSWORD_1]word@host:5432/dbname"
mcp-server-watchlist

# Use MySQL
export DATABASE_URL="mysql://user:[REDACTED_SQL_PASSWORD_1]word@host:3306/dbname"
mcp-server-watchlist

提示：

如果你想一直使用 watchlist.db repo目录中的文件，set DATABASE_URL 走向它的绝对道路。

export DATABASE_URL="sqlite:////absolute/path/to/your/repo/watchlist.db"
mcp-server-watchlist

一种衬里变体：

DATABASE_URL="sqlite:////absolute/path/to/your/repo/watchlist.db" mcp-server-watchlist

这确保了无论从何处运行命令，都使用相同的DB文件。

Windows注意事项：

在Windows上，使用三个斜线表示绝对路径（例如： sqlite:///C:/path/to/watchlist.db).使用四个斜线可能会导致以下问题 aiosqlite在PowerShell中：

$env:DATABASE_URL = "sqlite:///C:/path/to/watchlist.db"

如果 DATABASE_URL 如果未设置，该工具默认为名为的本地SQLite文件 watchlist.db 在当前目录中。

如果配置的值无效（例如，像这样的纯文件名 watchlist.db)，服务器将回退到默认的本地SQLite URL。

安全地重新解析依赖关系

如果您需要重新解析依赖关系（例如在编辑后 pyproject.toml):

uv lock
uv sync

此更新 uv.lock 和 .venv 到最新的兼容版本。

您不需要重新运行 uv tool install 重新解析依赖关系后，除非您想升级或刷新已安装的工具。

常见问题

• 代码更改后，MCP检查器中未显示新工具或提示： mcp-server-watchlist 是安装时的快照。从项目根目录重新安装：

  uv tool install --force --no-cache .

• 检查器将不会启动：验证Node.js是否已安装并位于PATH上 node -v 和 npx -v.

• 端口8000已在使用中：停止使用端口8000的进程或更改服务器端口。

• 检查器UI未打开：验证检查器是否正在运行并打开http://localhost:6274.

• Python版本问题：使用Python 3.12+（需要 pyproject.toml).与核对 python --version.

有关更多帮助，请参阅 FastMCP文档 或在此存储库中打开问题。

______________________________________________________________________

许可证

该项目根据MIT许可证获得许可。看 许可证 了解详情。