Skip to main content
Glama
semantic-product-search-mcp

semantic-product-search-mcp

by sebastian946

语义化商品搜索

语义化商品搜索:不是匹配关键词,而是理解查询意图(嵌入 + 相似度搜索),并使用智能体生成针对商品目录的推荐。商品目录以 MCP 服务器形式暴露,由独立的智能体消费。

🚧 项目正在积极开发中。当前处于第一阶段 · 后端搭建。 架构、演示和设计决策部分将在后续端到端流程可用时补充。

技术栈

  • API: FastAPI

  • 智能体 / 编排: LangChain + LangChain Anthropic (Claude)

  • 本地模型: Ollama

  • 可观测性: LangSmith

  • 配置 / 验证: Pydantic + Pydantic Settings

  • 数据库: Postgres + pgvector(本地开发:SQLite)

  • 包管理器: uv

Related MCP server: Product MCP Server

项目结构

app/
  main.py           # entrypoint de la API
  api/routes.py      # rutas HTTP
  catalog/           # ingesta + modelos de datos del catálogo
  search/             # embeddings + similarity search
  reviews/
  mcp_server/         # servidor MCP (expone el catálogo/búsqueda como tools)
  agent/               # agente que consume el MCP y arma la recomendación
  core/
    config.py         # settings (variables de entorno)
    db.py              # conexión a Postgres/pgvector
  models/
    schemas.py         # modelos Pydantic compartidos
tests/

本地搭建

要求:Python >= 3.12 并已安装 uv。

# Instalar dependencias
uv sync

# Configurar variables de entorno
cp .env.example .env
# completar ANTHROPIC_API_KEY y LANGSMITH_API_KEY en .env

# Correr el entrypoint
uv run python -m app.main

环境变量

变量

默认值

描述

ENVIRONMENT

development

运行环境

LANGSMITH_TRACING

false

启用 LangChain 在 LangSmith 中的追踪

LANGSMITH_ENDPOINT

https://api.smith.langchain.com

LangSmith 端点

LANGSMITH_API_KEY

(必填)

LangSmith API 密钥

LANGSMITH_PROJECT

SemanticProductSearch

LangSmith 中的项目名称

ANTHROPIC_API_KEY

(必填)

Anthropic (Claude) API 密钥

DATABASE_URL

sqlite:///./semantic_product_search.db

数据库连接字符串

EMBEDDING_MODEL

all-MiniLM-L6-v2

嵌入模型

MODEL_NAME

sentence-transformers/all-MiniLM-L6-v2

用于相似度搜索的模型

TOP_K

5

每次搜索返回的结果数量

⚠️ 切勿记录 API 密钥或任何机密信息的值(ANTHROPIC_API_KEY、LANGSMITH_API_KEY 等)。如果需要调试 Settings,仅打印失败的字段名称,而非其值——app/core/config.py 在启动时验证时正是这样做的。

路线图

开发按阶段组织(参见 Notion 看板):

  1. 后端搭建

  2. 商品目录 + 嵌入

  3. 语义搜索

  4. 评论 + 反馈

  5. MCP 服务器

  6. 智能体 + 推荐

  7. REST API + 流式传输

  8. 优化

  9. 前端 + 发布

架构与设计决策

待定——将在第九阶段(PROD-32)记录,届时项目具备端到端流程,可以基于实际上下文描述图表、演示和决策(缓存、检索 + 重排序等)。

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections.

Loading tool schema changelog…

    Related MCP Connectors

    Related MCP Servers