MCP Taw Utils

TAW Utils v2.0

全面的Firebase配置管理和AI模型实用程序

一个多界面工具集，提供MCP（模型上下文协议）服务器、REST API和CLI，用于管理Firebase配置、AI模型、MCP插件和部署基础设施。

特性

• 🔧 共享工具库 -与框架无关的业务逻辑
• 🤖 MCP服务器 -用于AI代理集成的Stdio/SSE传输
• 🌐 OpenAPI REST服务器 -带有Swagger文档的HTTP REST API
• ⚡ 独立CLI -不需要服务器依赖关系
• 🔐 安全第一 -基于环境的配置，没有硬编码的秘密
• 🎯 灵活部署 -独立或一起运行服务器
• 📦 TypeScript -全程全型安全

快速开始

先决条件

• Node.js 20或更高版本
• Firebase管理员服务帐户凭据
• Git

安装

# Clone the repository
git clone https://github.com/modellers/mcp-taw-utils.git
cd mcp-taw-utils

# Install dependencies
npm install

# Create secrets directory and add your Firebase service account
mkdir secrets
# Place your service account JSON at: ./secrets/tasking-agency-serviceaccount.json

# Create .env file from example
cp .env.example .env
# Edit .env with your configuration

# Build the project
npm run build

验证安装

# Validate configuration
npm run cli -- config validate

# Check health
npm run cli -- health

用法

1.CLI（独立-无需服务器）

# Using npm scripts
npm run cli -- config list

# Or use the installed binary
node dist/cli/index.js config list

# After installing globally
npm install -g .
taw-utils config list

可用命令：

# Config management
taw-utils config list                    # List all config documents
taw-utils config get                 # Get a document by ID
taw-utils config set  --file data.json  # Create/update document
taw-utils config validate                # Validate configuration

# Health check
taw-utils health                         # Check Firebase connection

# Model management (coming soon)
taw-utils models list
taw-utils models update --provider openai
taw-utils models upload --dry-run

# Plugin management (coming soon)
taw-utils plugins discover 
taw-utils plugins upload --library library.json

# Firebase utilities (coming soon)
taw-utils firebase user-create  

taw-utils firebase copy --collections tasking,task

# Managed servers (coming soon)
taw-utils managed generate --dir ./servers/prod
taw-utils managed build --dir ./servers/prod

# Binary distribution (coming soon)
taw-utils binaries upload --platform mac

2.MCP服务器（用于AI代理）

# Start MCP server only (stdio)
npm run start:mcp

# Or with both servers
npm start

可用的MCP工具：

• mcp_collection_list -列出所有配置文档
• mcp_collection_get -按ID获取文档
• mcp_collection_set -创建/更新文档
• mcp_collection_item_from_git -解析Git URI
• mcp_collection_item_set -更新Git配置

MCP客户端配置：

{
  "mcpServers": {
    "mcp-taw-utils": {
      "command": "node",
      "args": ["/path/to/mcp-taw-utils/dist/servers/mcp.js"]
    }
  }
}

3.OpenAPI REST服务器

# Start API server only
npm run start:api

# Or with both servers
npm start

API服务器默认运行在端口3004上（可通过 API_SERVER_PORT).

终点：

GET    /health                # Health check
GET    /                      # API documentation

# Config collection
GET    /api/config            # List all documents
GET    /api/config/:id        # Get document
POST   /api/config/:id        # Create document
PUT    /api/config/:id        # Update document

# Git utilities
POST   /api/git/parse         # Parse Git URI
POST   /api/git/config/:id    # Update Git config

示例：

# Health check
curl http://localhost:3004/health

# List config documents
curl http://localhost:3004/api/config

# Get specific document
curl http://localhost:3004/api/config/models-openai

# Create/update document
curl -X POST http://localhost:3004/api/config/my-doc \
  -H "Content-Type: application/json" \
  -d '{"type":"test","data":"value"}'

# Parse Git URI
curl -X POST http://localhost:3004/api/git/parse \
  -H "Content-Type: application/json" \
  -d '{"uri":"https://github.com/user/repo.git"}'

使用身份验证：

# Set in .env
API_AUTH_ENABLED=true
API_KEY=your-secret-key

# Use in requests
curl http://localhost:3004/api/config \
  -H "X-API-Key: your-secret-key"

配置

环境变量

创建 .env 文件（参见 .env.example 对于所有选项）：

# Required
FIREBASE_PROJECT_ID=tasking-agency-is
FIREBASE_STORAGE_BUCKET=tasking-agency-is.appspot.com
FIREBASE_SERVICE_ACCOUNT_PATH=./secrets/tasking-agency-serviceaccount.json

# Server Configuration
MCP_SERVER_ENABLED=true
MCP_SERVER_PORT=3023          # 0 = disabled (stdio only)
MCP_TRANSPORT=stdio           # stdio | sse | both

API_SERVER_ENABLED=true
API_SERVER_PORT=3004          # 0 = disabled
API_AUTH_ENABLED=false
API_KEY=your-secret-key

# Optional - AI Service API Keys
OPENAI_API_KEY=sk-...
ANTHROPIC_API_KEY=sk-ant-...
GOOGLE_API_KEY=AIza...
MISTRAL_API_KEY=...
GITHUB_TOKEN=ghp_...

服务器模式

两台服务器（默认）：

npm start
# MCP on stdio, API on port 3004

仅限MCP：

npm run start:mcp
# or
MCP_SERVER_ENABLED=true API_SERVER_ENABLED=false npm start

仅限API：

npm run start:api
# or
API_SERVER_ENABLED=true MCP_SERVER_ENABLED=false npm start

禁用MCP端口（仅限标准）：

MCP_SERVER_PORT=0 npm start

禁用API服务器：

API_SERVER_PORT=0 npm start

建筑

src/
├── tools/              # Shared business logic (framework-agnostic)
│   ├── config/        # Config collection tools
│   ├── models/        # Model management (coming soon)
│   ├── plugins/       # Plugin discovery (coming soon)
│   ├── firebase/      # Firebase utilities (coming soon)
│   ├── managed/       # Managed servers (coming soon)
│   └── binaries/      # Binary upload (coming soon)
├── cli/
│   ├── index.ts       # CLI entry point
│   └── commands/      # Command handlers
├── servers/
│   ├── mcp.ts         # MCP server
│   ├── api.ts         # OpenAPI server
│   └── index.ts       # Server launcher
├── types/             # TypeScript interfaces
├── utils/             # Utilities (firebase, logger)
└── config.ts          # Configuration system

关键原则：

1. 所有业务逻辑都存在于 src/tools/ -纯函数，无框架依赖
2. CLI/MCP/API是精简包装 -仅传输层
3. 每个工具都可以独立执行 -可以直接导入和使用
4. 基于环境的配置 -没有硬编码的秘密

发展

构建

npm run build

观看模式

npm run watch

运行测试

npm test                # Run all tests
npm run test:unit       # Run unit tests only
npm run test:coverage   # Run with coverage

添加新工具

1. 在中创建工具功能 src/tools/[category]/:

// src/tools/models/updateModelList.ts
export async function updateModelList(options: UpdateModelsOptions): Promise {
  // Business logic here
  return { success: true, data: models };
}

1. 在中添加CLI命令 src/cli/commands/[category].ts:

export const modelsCommand = {
  async list() {
    const result = await updateModelList({ provider: 'all' });
    console.log(JSON.stringify(result.data, null, 2));
  }
};

1. 在中添加MCP工具 src/servers/mcp.ts:

case "update_model_list":
  result = await updateModelList(args);
  break;

1. 在中添加API终结点 src/servers/api.ts:

app.post("/api/models/update", async (req, res) => {
  const result = await updateModelList(req.body);
  res.json(result);
});

安全

最佳实践

• ✅ 永远不要泄露秘密 -使用 .env 文件（忽略git）
• ✅ 服务帐户发现 -自动回退到多个路径
• ✅ 环境验证 -如果缺少所需的秘密，则会很快失败
• ✅ API认证 -可选API密钥/JWT支持
• ✅ 审核日志记录 -带级别的结构化日志记录

安全检查列表

1. 创建 .env 文件来自 .env.example
2. 将服务帐户JSON添加到 secrets/ 目录
3. 验证 .gitignore 包含 .env 和 secrets/
4. 在生产中启用API身份验证(API_AUTH_ENABLED=true)
5. 使用强API密钥(API_KEY=...)
6. 查看Firebase服务帐户权限
7. 定期旋转按键（建议：90天）

从Python脚本迁移

这 bin/ 目录包含原始Python脚本。这些正在迁移到Node.js：

当前阶段： ✅ 项目结构、配置和服务器 🚧 核心工具实施（下一阶段）

文档

• -原始需求和Python脚本文档
• CLAUDE.md -项目概况
• .env.example -完整的环境变量引用

故障排除

配置问题

# Validate your configuration
npm run cli -- config validate

# Check Firebase connection
npm run cli -- health

常见错误

错误：“未找到Firebase服务帐户”

# Solution: Create secrets directory and add service account
mkdir secrets
cp /path/to/serviceaccount.json ./secrets/tasking-agency-serviceaccount.json

错误：“未启用服务器”

# Solution: Enable at least one server
# In .env:
MCP_SERVER_ENABLED=true
# OR
API_SERVER_ENABLED=true

错误：“需要FIREBASE_PROJECT_ID”

# Solution: Add to .env
FIREBASE_PROJECT_ID=your-project-id

贡献

1. 分叉存储库
2. 创建要素分支
3. 进行更改
4. 添加测试
5. 提交拉取请求

许可证

麻省理工学院

支持

对于问题和疑问：

• GitHub问题：https://github.com/modellers/mcp-taw-utils/issues
• 文件：见

______________________________________________________________________

版本： 2.0.0 最后更新时间： 2025年12月11日