Mal Workspace

MAL 工作区

MyAnimeList 数据库、MCP 服务器、抓取器和聊天客户端的统一工作空间。

🚀 快速入门

# Install all dependencies
npm install

# Start PostgreSQL database
npm run docker:up

# Run migrations and seed data
npm run db:migrate
npm run db:seed

# Start the API server
npm run db:dev

📁 项目结构

mal-workspace/
├── database/own-mal-db/         # PostgreSQL database + REST API
├── mcp-servers/                 # MCP servers for Claude
│   ├── anime-search-mcp/
│   ├── mal-user-mcp/
│   └── anime-recommendation-mcp/
├── chat-client/                 # Interactive CLI client
├── shared/types/                # Shared TypeScript types
└── docker-compose.yml           # Infrastructure

🔧 可用命令

数据库操作

npm run db:dev          # Start development server
npm run db:start        # Start production server
npm run db:migrate      # Run database migrations
npm run db:seed         # Seed initial data

网络爬虫

npm run scraper:anime          # Scrape anime data
npm run scraper:reviews        # Scrape reviews
npm run scraper:check-stats    # Check database stats
npm run scraper:track-growth   # Track data growth

MCP 服务器

npm run mcp:build-all          # Build all MCP servers
npm run mcp:anime-search       # Start anime search MCP
npm run mcp:mal-user           # Start user operations MCP
npm run mcp:recommendation     # Start recommendation MCP

聊天客户端

npm run dev:chat               # Start interactive chat client

Docker 操作

npm run docker:up              # Start all containers
npm run docker:down            # Stop all containers
npm run docker:logs            # View container logs

🎯 使用MCP服务器与Claude

1. 构建MCP服务器：

npm run mcp:build-all

1. 添加到您的Claude桌面配置中（~/.config/claude/claude_desktop_config.json):

{
  "mcpServers": {
    "anime-search": {
      "command": "node",
      "args": ["/absolute/path/to/mal-workspace/mcp-servers/anime-search-mcp/build/server.js"]
    },
    "mal-user": {
      "command": "node",
      "args": ["/absolute/path/to/mal-workspace/mcp-servers/mal-user-mcp/build/server.js"]
    },
    "anime-recommendation": {
      "command": "node",
      "args": ["/absolute/path/to/mal-workspace/mcp-servers/anime-recommendation-mcp/build/server.js"]
    }
  }
}

1. 重启Claude桌面版

💬 使用聊天客户端

聊天客户端提供了一个交互式命令行界面（CLI）来测试MCP功能：

cd chat-client
npm install
npm run dev

特点：

• 🔍 按名称搜索动漫
• ⭐ 获取个性化推荐
• 📊 浏览季节性动漫
• 🎭 按类型筛选
• 👤 用户操作（使用MAL OAuth）

⚙️ 配置

数据库配置

复制环境文件并进行配置：

cp database/own-mal-db/env.example database/own-mal-db/.env

编辑 .env：

DATABASE_URL=postgresql://mal_user:your_password@localhost:5433/mal_db
PORT=3001
NODE_ENV=development

MAL用户MCP（OAuth）

对于用户操作，请配置OAuth：

cp mcp-servers/mal-user-mcp/.env.example mcp-servers/mal-user-mcp/.env

从以下网址获取凭据：https://myanimelist.net/apiconfig

📊 API 文档

一旦API运行起来，请访问：

http://localhost:3001/docs

由Scalar提供支持的交互式API文档。

🛠️ 开发

添加新的MCP服务器

1. 在（指定位置）创建目录 mcp-servers/
2. 添加到根目录的工作区 package.json
3. 添加npm脚本以便轻松访问
4. 更新 ARCHITECTURE.md

运行测试

# Run tests in specific workspace
npm run test --workspace=database/own-mal-db

📚 文档

• ARCHITECTURE.md 翻译为中文是：“架构.md”（其中，“.md”通常表示Markdown格式的文件） - 详细的系统架构
• 数据库/自定义恶意软件数据库/README.md - 数据库文档
• \mcp-servers/anime-search-mcp/README.md\ 翻译成中文为：\mcp-servers/动漫搜索-mcp/README.md\（注：这里的“anime-search-mcp”被直译为“动漫搜索-mcp”，在实际应用中，根据上下文，“anime-search-mcp”可能是一个特定项目或模块的名称，直接保留原英文或稍作调整以符合项目命名习惯也是可接受的，但在此处按照直译进行翻译。） - 动漫搜索MCP
• \mcp-servers/mal-user-mcp/README.md\ 翻译成中文为：\mcp服务器/mal用户mcp/README.md\（注：这里的“mal-user-mcp”可能是一个特定项目或服务的名称，根据上下文，“mal”可能代表某个特定的服务、平台或项目，但在此直接翻译为“mal用户mcp”以保持原样，实际含义需结合具体上下文理解。） - 用户操作MCP（管理控制面板/多云平台等，具体含义需根据上下文确定）

🔄 从旧结构迁移

这个工作区整合了多个独立项目：

• ../own-mal-db → database/own-mal-db
• ../anime-search-mcp → mcp-servers/anime-search-mcp
• ../mal-user-mcp → mcp-servers/mal-user-mcp
• ../anime-recommendation-mcp → mcp-servers/anime-recommendation-mcp

确认工作区运行正常后，可以将原始文件夹归档。

🐛 故障排除

数据库连接失败

# Check if PostgreSQL is running
npm run docker:logs

# Verify connection settings in .env

MCP服务器无法连接

# Rebuild the servers
npm run mcp:build-all

# Check absolute paths in Claude config

抓取速率受限

• 抓取程序实现了检查点系统
• 从上一个成功检查点恢复
• 调整爬虫脚本中的速率限制

🤝 贡献

1. 在工作区包内工作
2. 使用来自（某处/某库）的共享类型 shared/types
3. 更新文档
4. 在提交之前测试MCP功能

📝 许可证

MIT - 请参阅各个包中的LICENSE文件

🙏 致谢

• 用于动漫数据的MyAnimeList
• Jikan API 用于非官方 MAL API
• 适用于MCP SDK的Anthropic（注：此处“Anthropic”可能指的是某个特定于MCP SDK的库、框架或工具，但根据上下文无法确定其具体含义，因此直接翻译为“适用于MCP SDK的Anthropic”，实际翻译可能需根据具体语境调整）

______________________________________________________________________

作者利奥·瓦伊尼奥 版本1.0.0