Requirements Advisor

需求顾问MCP服务器

MCP（模型上下文协议）服务器，为Jama Softare的“需求管理和可追溯性基本指南”中的需求管理最佳实践提供专家指导。未来的版本将添加INCOSE指南和EARS文档中的最佳实践。

特性

• FastMCP服务器：具有流式HTTP传输的远程MCP服务器，与任何LLM兼容
• 矢量搜索：需求管理指导的语义搜索
• 多源：支持多个权威来源（Jama Guide、INCOSE、EARS）
• Voyage AI嵌入：针对技术内容优化的高质量嵌入
• Docker就绪：容器化，便于部署
• 抽象层：交换嵌入提供程序或矢量存储，无需更改代码

快速开始

先决条件

• Docker和Docker Compose
• Voyage AI API键(在这里买一个)
• 内容文件（JSONL格式） content/ 目录

1.克隆和配置

cd requirements-advisor

# Create environment file
cp .env.example .env

# Edit .env and add your Voyage API key
nano .env  # or use your preferred editor

2.添加内容

将您抓取的内容放在 content/ 目录：

• requirements_management_guide.jsonl -Jama Guide（来自Jama导轨刮刀）
• incose_gwr.jsonl -INCOSE指南（未来）
• ears_notation.jsonl -EARS文件（未来）

3.构建和运行

# Build the container
docker compose build

# Ingest content into vector store
docker compose run --rm ingestion

# Start the server
docker compose up -d

# Check logs
docker compose logs -f mcp-server

MCP服务器现在正在运行 http://localhost:8000/mcp

______________________________________________________________________

部署场景

场景A:Jama高管演示

目标：快速演示MCP服务器功能

选项1：本地演示（推荐给高管）

会议期间在笔记本电脑上运行：

# Ensure content is ingested
docker compose run --rm ingestion

# Start server
docker compose up

# Server available at http://localhost:8000/mcp

连接Claude Desktop或任何兼容MCP的客户端（请参阅下面的“连接客户端”）。

选项2：云演示（可共享链接）

部署到云提供商以获取持久演示URL：

铁路（最简单）

# Install Railway CLI
npm install -g @railway/cli

# Login and deploy
railway login
railway init
railway up

# Set environment variables in Railway dashboard
# Get public URL from Railway

渲染

# Create render.yaml
# Push to GitHub
# Connect repo in Render dashboard
# Set VOYAGE_API_KEY in environment

AWS/GCP/Azure

# Build and push to container registry
docker build -t requirements-advisor .
docker tag requirements-advisor:latest /requirements-advisor:latest
docker push /requirements-advisor:latest

# Deploy to ECS/Cloud Run/Container Apps

对于任何云部署，您都需要：

1. 保留ChromaDB卷或迁移到受管向量存储
2. 集 VOYAGE_API_KEY 作为环境变量/秘密
3. 配置适当的网络/防火墙规则

______________________________________________________________________

场景B：笔记本电脑的本地开发

目标：在本地运行所有内容以进行开发和测试

使用Docker（推荐）

# 1. Start everything
docker compose up

# 2. In another terminal, test the search
docker compose exec mcp-server python -m requirements_advisor.cli test-search "how to write requirements"

# 3. Make changes and rebuild
docker compose up --build

使用UV（无Docker）

# 1. Install UV if not already installed
curl -LsSf https://astral.sh/uv/install.sh | sh

# 2. Create virtual environment and install dependencies
uv sync

# 3. Set up environment
cp .env.example .env
# Edit .env with your VOYAGE_API_KEY

# 4. Ingest content
uv run requirements-advisor ingest

# 5. Start server
uv run requirements-advisor serve

# 6. Or run directly with Python
source .venv/bin/activate
python -m requirements_advisor.cli serve

使用pip（传统）

# 1. Create virtual environment
python -m venv .venv
source .venv/bin/activate  # Windows: .venv\Scripts\activate

# 2. Install package
pip install -e .

# 3. Configure and run
cp .env.example .env
# Edit .env
requirements-advisor ingest
requirements-advisor serve

______________________________________________________________________

连接MCP客户端

克劳德桌面版

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

{
  "mcpServers": {
    "requirements-advisor": {
      "url": "http://localhost:8000/mcp"
    }
  }
}

重新启动Claude Desktop以进行连接。

克劳德代码

# Add the MCP server
claude mcp add requirements-advisor --url http://localhost:8000/mcp

其他MCP客户端

任何兼容MCP的客户端都可以通过Streamable HTTP传输连接到：

http://localhost:8000/mcp

对于远程部署，请替换 localhost:8000 使用您的服务器URL。

______________________________________________________________________

MCP服务器规范

服务器元数据

工具

此服务器公开了4个工具。未提供任何资源或提示。

search_requirements_guidance

搜索需求管理最佳实践和指导。

退货： 相关指导摘录列表，包括源引用和可选图像。

用途： 编写要求、可追溯性、验证/确认、监管合规性、系统工程、行业特定实践（医疗、汽车、航空航天）。

______________________________________________________________________

get_definition

获取需求管理术语或缩写词的定义。

退货： 定义和来源归因。

用途： SRS、EARS、可追溯性、V&V、RTM和其他需求管理术语等术语。

______________________________________________________________________

list_available_topics

列出知识库中可用的主题和来源。

退货： 可用主题、来源和文档数的摘要。

用途： 在搜索之前了解可用的指导。

______________________________________________________________________

get_best_practices

获取特定需求管理主题的最佳实践。

退货： 最佳实践，包括解释、源引用和可选图像。

用途： 主题包括编写需求、可追溯性、验证、变更管理、法规遵从性、敏捷需求。

______________________________________________________________________

查询示例

"How do I write good functional requirements?"
"What is requirements traceability and why does it matter?"
"Best practices for medical device requirements"
"Define EARS notation"
"What are non-functional requirements?"

______________________________________________________________________

CLI命令

# Start the MCP server
requirements-advisor serve [--host 0.0.0.0] [--port 8000]

# Ingest content into vector store
requirements-advisor ingest [--content-dir ./content] [--clear]

# Show configuration and status
requirements-advisor info

# Test a search query
requirements-advisor test-search "your query here" [--top-k 5]

______________________________________________________________________

项目结构

requirements-advisor/
├── pyproject.toml              # Python package configuration
├── Dockerfile                  # Container image definition
├── docker-compose.yml          # Multi-container orchestration
├── .env.example                # Environment template
├── src/requirements_advisor/
│   ├── __init__.py
│   ├── cli.py                  # Typer CLI commands
│   ├── config.py               # Pydantic settings
│   ├── logging.py              # Loguru logging configuration
│   ├── server.py               # FastMCP server + tools
│   ├── embeddings/
│   │   ├── base.py             # Abstract interface
│   │   └── voyage.py           # Voyage AI implementation
│   ├── vectorstore/
│   │   ├── base.py             # Abstract interface
│   │   └── chroma.py           # ChromaDB implementation
│   ├── images/
│   │   ├── base.py             # Image models (CachedImage, ImageIndex)
│   │   └── cache.py            # Image fetching and caching
│   └── ingestion/
│       └── pipeline.py         # Content ingestion
├── tests/                      # Test suite
│   ├── conftest.py             # Pytest fixtures
│   └── test_*.py               # Test modules
├── content/                    # JSONL content files
│   └── requirements_management_guide.jsonl
└── data/                       # Persistent data (gitignored)
    ├── chroma/                 # Vector store
    └── images/                 # Cached images

______________________________________________________________________

配置

所有配置均通过环境变量（或 .env 文件）：

______________________________________________________________________

未来的增强功能

• \[\]Qdrant矢量存储支持远程/托管部署
• \[\]其他嵌入提供商（OpenAI、Cohere）
• \[\]INCOSE编写要求内容指南
• \[\]EARS符号文档
• \[\]Kubernetes部署的Helm chart
• \[\]身份验证/API密钥支持
• \[\]使用情况分析和反馈

______________________________________________________________________

故障排除

“未设置VOYAGE_API_KEY”

• 确保 .env 存在具有有效API密钥的文件
• 检查密钥已导出： echo $VOYAGE_API_KEY

“矢量存储中没有文档”

• 跑步摄入： docker compose run --rm ingestion
• 检查内容目录是否有JSONL文件

客户端“连接被拒绝”

• 确保服务器正在运行： docker compose ps
• 检查端口8000是否堵塞
• 验证客户端配置中的URL是否与服务器匹配

Docker构建失败

• 确保Docker正在运行
• 尝试： docker compose build --no-cache

______________________________________________________________________

许可证

MIT许可证-有关详细信息，请参阅许可证文件。