AI导哈

影视内容追踪服务

一个通过自然语言处理帮助用户追踪观看过的影视、动漫内容的API服务，支持批量记录、历史查询和智能消歧。

  • by kofort9
  • TypeScript
  • 本地部署
  • 更新于
在 GitHub 查看 kofort9/trakt.tv-mcp

使用说明

网站.tv-mcp

Trakt.tv API的MCP服务器-使人工智能助手能够使用自然语言跟踪观看的节目、电影和动画

项目链接

  • 存储库：https://github.com/kofort9/trakt.tv-mcp
  • 问题：https://github.com/kofort9/trakt.tv-mcp/issues
  • 安全：请参阅 安全.md

特性

  • 自然语言支持：使用会话短语，如“昨天看的”、“今晚”、“3天前”、“上周一”
  • 跟踪观看的内容：用灵活的日期表达方式记录电影和电视节目
  • 批量日志记录：使用范围支持同时录制多集或多部电影（“第1-5集”）
  • 批量导入脚本：从CSV文件导入100多个历史条目(请参阅指南)
  • 观看历史：按日期范围查询和汇总您的查看历史记录
  • 搜索：在Trakt.TV上查找电影、电视节目和动漫
  • 智能消歧：自动处理多个版本或年份的内容
  • OAuth 2.0身份验证：与您的Trakt.tv帐户安全集成
  • 廊坊可观察性：全面的AI原生跟踪和监控(请参阅文档)

快速开始

对于用户

自然语言示例：

"Watched Breaking Bad S1E1 yesterday"
"Binged episodes 1-5 of Demon Slayer tonight"
"What did I watch last week?"
"Watched Dune 2021 last Friday"

看 自然语言指南 获取完整的使用文档。

离线捕捉 logwatch

当无法访问Claude/AI时，在本地排队并稍后进行对账。我们只存储您提供的原始文本，不进行解析或摘要。

  • logwatch "yesterday watched The Bear S2E5" -将原始注释附加到 ~/.trakt-mcp/pending-logs.jsonl
  • logwatch list -检查队列
  • 自动跳过重复的原始钞票；重新运行相同的输入将指向已排队的条目。

使用以下命令全局安装CLI npm install -g 在此repo或run中 npm link 同时发展。队列使用仅限所有者的权限（600），并遵循 手动E2E计划 用于离线捕获。

人工智能助理（Claude）

该服务器专为AI助手集成而设计。看 贡献指南-人工智能助理科 用于：

  • 如何解释用户查询
  • 自然语言模式映射
  • 错误处理和消歧
  • 会话交互的最佳实践

文档

📚 完整文档索引

快速链接：

安全

日志和数据隐私

  • 日志目录：日志存储在 ~/.trakt-mcp/logs （用户主目录）。
  • 权限:
    • 目录权限限制为 0o700 （仅限所有者读/写/执行）。
    • 日志文件仅限于 0o600 （仅限所有者读/写）。
  • 保留:
    • 当日志达到10MB时，会自动轮换。
    • 最多保留10个日志文件（可通过以下方式配置 maxLogFiles).
    • 超过7天的日志将自动删除（可通过配置 maxLogAge).
  • 编辑：敏感标题，如 Authorization 从所有日志中删除。
  • 平台说明:
    • 权限强制在Linux和macOS（POSIX）上处于活动状态。
    • 在Windows上，文件权限不是由严格执行的 chmod。确保日志目录位于安全的、特定于用户的位置。

令牌存储

  • 位置：OAuth令牌存储在 ~/.trakt-mcp/.trakt-token.json
  • 权限：令牌文件是使用创建的 0o600 （仅限所有者读/写）
  • 目录：使用创建的父目录 0o700 （仅限所有者）

OAuth身份验证

OAuth设备流包括防止竞争条件的保护措施：

  • 并发投票预防：一次只能运行一个轮询操作
  • 取消支持：使用 cancelPolling() 中止正在进行的身份验证
  • 状态检测：检查 isPollingInProgress() 在开始新的民意调查之前
  • 自动清理：轮询状态在完成或出错后始终重置

发展

先决条件

  • Node.js 20.x或更高版本
  • npm
  • Trakt.tv帐户和API凭据

回购包括 .nvmrc （20.19.6）和a preinstall 在Node<20上快速失败的防护程序。使用 nvm use 或 export PATH="/opt/homebrew/opt/node@20/bin:$PATH" 如果你在Homebrew上。

设置

# Install dependencies
npm install

# Copy environment template
cp .env.example .env

# Add your Trakt.tv credentials to .env
# TRAKT_CLIENT_ID=your_client_id
# TRAKT_CLIENT_SECRET=your_client_secret

Claude桌面集成

使用 run-mcp.sh Claude Desktop集成的包装器脚本。此包装：

  • 抑制dotenv横幅输出以进行干净的JSON-RPC通信
  • 使用动态路径解析（适用于任何目录）
  • 运行前验证构建是否存在

配置示例：

添加到您的Claude桌面配置(~/Library/Application Support/Claude/claude_desktop_config.json 在macOS上）：

{
  "mcpServers": {
    "trakt": {
      "command": "/absolute/path/to/trakt.tv-mcp/run-mcp.sh"
    }
  }
}

备注：始终使用包装器脚本，而不是运行 node dist/index.js 直接。直接执行将导致Claude Desktop中的协议错误。包装套 DOTENV_CONFIG_QUIET=true 以抑制否则会污染stdout的dotenv横幅，从而破坏MCP JSON-RPC协议。

可用脚本

# Build the project
npm run build

# Run in development mode with auto-reload
npm run dev

# Run linter
npm run lint

# Fix linting issues
npm run lint:fix

# Check code formatting
npx prettier --check "src/**/*.ts"

# Format code
npm run format

# Run tests
npm test

# Run tests in watch mode
npm run test:watch

# Run tests with UI
npm run test:ui

# Bulk import historical data from CSV
npm run bulk-import -- --help

代码质量

本项目使用：

  • TypeScript 具有严格的型号安全模式
  • ESLint 用于代码过滤
  • 更漂亮 用于代码格式化
  • Vitest 用于测试

所有代码更改都必须通过：

  • TypeScript编译
  • ESLint检查
  • 预处理格式检查
  • 所有单元测试

持续集成

GitHub Actions会自动对每个推送和拉取请求进行质量检查：

  • TypeScript编译
  • ESLint验证
  • 预分级格式验证
  • 完整的测试套件
  • 安全审计

看 分支保护建议 用于设置分支保护规则。

贡献与人工智能集成

该项目专为AI助手集成（Claude等）而设计。关键资源：

  1. CLAUDE.md -AI助手的项目架构和指南
  2. 贡献指南 -AI集成模式和自然语言支持
  3. 自然语言指南 -日期/时间解析文档

所有更改都必须通过测试和代码质量检查。

支持

许可证

麻省理工学院

相关 MCP