使用说明

NAICS MCP服务器

基于模型上下文协议（MCP）构建的NAICS 2022智能行业分类服务。

特性

语义搜索 -使用句子嵌入的自然语言搜索
混合搜索 -将语义理解与精确术语匹配相结合
5级层次结构 -从部门（2位）导航到国家工业（6位）
交叉引用集成 -准确分类的关键排除检查
索引词搜索 -20398 NAICS官方索引术语
分类工作簿 -记录和跟踪分类决策
健康监测 -Kubernetes就绪活性和就绪性探针

快速开始

使用Docker（推荐）

# Clone the repository
git clone https://github.com/your-org/naics-mcp-server.git
cd naics-mcp-server

# Start the server
docker compose up

使用pip

# Install
pip install naics-mcp-server

# Initialize database
naics-mcp init

# Generate embeddings
naics-mcp embeddings

# Run the server
naics-mcp-server

安装

来自PyPI

pip install naics-mcp-server

源自

git clone https://github.com/your-org/naics-mcp-server.git
cd naics-mcp-server
pip install -e .

具有发展依赖性

pip install -e ".[dev]"

配置

服务器是通过具有合理默认值的环境变量配置的。

核心设置

变量	默认值	描述
`NAICS_DATABASE_PATH`	`~/.cache/naics-mcp-server/naics.duckdb`	DuckDB数据库的路径
`NAICS_EMBEDDING_MODEL`	`all-MiniLM-L6-v2`	句子转换模型
`NAICS_DEBUG`	`false`	启用调试模式

搜索设置

变量	默认值	描述
`NAICS_HYBRID_WEIGHT_SEMANTIC`	`0.7`	语义搜索权重（0-1）
`NAICS_MIN_CONFIDENCE`	`0.3`	最小置信阈值
`NAICS_DEFAULT_LIMIT`	`10`	默认结果限制
`NAICS_QUERY_TIMEOUT_SECONDS`	`5`	查询超时

功能标志

变量	默认值	描述
`NAICS_ENABLE_QUERY_EXPANSION`	`true`	使用同义词展开查询
`NAICS_ENABLE_CROSS_REFERENCES`	`true`	包括交叉引用检查
`NAICS_ENABLE_AUDIT_LOG`	`true`	用于审计的日志搜索查询

日志记录

变量	默认值	描述
`NAICS_LOG_LEVEL`	`INFO`	日志级别（调试、信息、警告、错误）
`NAICS_LOG_FORMAT`	`text`	日志格式(`text` 或 `json`)
`NAICS_LOG_FILE`	`None`	日志的可选文件路径

示例 `.env` 文件

# Database
NAICS_DATABASE_PATH=/data/naics.duckdb

# Search tuning
NAICS_HYBRID_WEIGHT_SEMANTIC=0.7
NAICS_MIN_CONFIDENCE=0.3

# Logging
NAICS_LOG_LEVEL=INFO
NAICS_LOG_FORMAT=json

# Debug (disable in production)
NAICS_DEBUG=false

码头工人

使用Docker Compose

# Start production server
docker compose up -d

# View logs
docker compose logs -f

# Stop
docker compose down

发展模式

# Start with hot reload and debug logging
docker compose --profile dev up naics-dev

初始化数据库

# Initialize database schema
docker compose --profile init run naics-init

# Generate embeddings (takes a few minutes)
docker compose --profile init run naics-embeddings

塑造形象

# Build production image
docker build -t naics-mcp-server:latest --target runtime .

# Build development image
docker build -t naics-mcp-server:dev --target development .

Docker卷

卷	目的
`naics-mcp-data`	数据库存储
`naics-mcp-cache`	模型缓存（句子转换器）
`naics-mcp-logs`	应用程序日志

Kubernetes

使用Kustomize部署到Kubernetes：

# Deploy base configuration
kubectl apply -k k8s/base/

# Deploy production overlay (scaled resources)
kubectl apply -k k8s/overlays/production/

部署包括：

活力、准备和启动探测
数据库和模型缓存的持久存储
基于ConfigMap的配置
Prometheus操作员服务监视器

看 k8s/README.md 获取完整的Kubernetes部署文档。

MCP工具

搜索工具

工具	说明
`search_naics_codes`	具有置信度评分的混合语义/词汇搜索
`search_index_terms`	搜索官方20398术语NAICS索引
`find_similar_industries`	使用嵌入查找与给定代码相似的代码
`classify_batch`	高效地对多个业务描述进行分类

层次结构工具

工具	说明
`get_code_hierarchy`	获取完整的祖先链（扇区→ 国家工业）
`get_children`	获取代码的直系子女
`get_siblings`	获取与同一父级处于同一级别的代码

分类工具

工具	说明
`classify_business`	用详细的推理对描述进行分类
`get_cross_references`	获取代码的排除项/包含项
`validate_classification`	验证代码是否与描述一致

分析工具

工具	说明
`get_sector_overview`	部门/子部门结构摘要
`compare_codes`	多个代码的并排比较

工作簿工具

工具	说明
`write_to_workbook`	记录分类决策
`search_workbook`	搜索过去的决策
`get_workbook_entry`	检索特定条目
`get_workbook_template`	获取结构化输入的表单模板

诊断工具

工具	说明
`ping`	简单的活性检查
`check_readiness`	检查服务器是否已准备好处理请求
`get_server_health`	所有组件的详细健康状况
`get_workflow_guide`	获取推荐的分类工作流程

CLI使用情况

# Run the MCP server
naics-mcp serve

# Search for NAICS codes
naics-mcp search "retail grocery store"
naics-mcp search "dog food manufacturing" --strategy semantic --limit 5

# View code hierarchy
naics-mcp hierarchy 445110

# Show database statistics
naics-mcp stats

# Initialize/rebuild database
naics-mcp init

# Generate/rebuild embeddings
naics-mcp embeddings
naics-mcp embeddings --rebuild  # Force rebuild

# Batch classify from CSV
naics-mcp classify-batch suppliers.csv
naics-mcp classify-batch suppliers.csv --column "supplier_name"
naics-mcp classify-batch suppliers.csv --top-n 3 --output results.csv

批次分类

在一个命令中对数千个业务描述进行分类。读取CSV，通过混合搜索引擎运行每一行，并使用NAICS代码、标题、级别和置信度评分写入结果。

naics-mcp classify-batch suppliers.csv --column description --top-n 3 --strategy hybrid

选项	默认值	描述
`--column`	`description`	包含业务描述的CSV列
`--output`	`<input>_classified.csv`	输出文件路径
`--top-n`	`1`	每行排名靠前的比赛数量
`--strategy`	`hybrid`	搜索策略(`hybrid`, `semantic`, `lexical`)

输出保留所有原始列并附加分类列。随着 --top-n 3，列带有后缀(naics_code_1, naics_code_2, naics_code_3等等）。每500行报告一次进度，包括速率和预计到达时间。

健康检查

服务器提供HTTP端点和MCP工具用于健康监控。

HTTP端点（端口9090）

端点	目的	用途
`GET /health`	Liveness probe	Kubernetes livessProbe
`GET /ready`	就绪性探测	Kubernetes就绪性探测
`GET /status`	详细状态	监控仪表板
`GET /metrics`	普罗米修斯指标	普罗米修斯抓取

# Check if server is alive
curl http://localhost:9090/health
# {"status": "alive", "timestamp": "2024-01-15T10:30:00Z"}

# Check if ready for traffic
curl http://localhost:9090/ready
# {"status": "ready", "uptime_seconds": 120.5, "timestamp": "..."}

# Get Prometheus metrics
curl http://localhost:9090/metrics

看 docs/HTTP_ENDPOINTS.md 获取完整的HTTP API文档。

MCP工具

工具	目的
`ping`	简单的活性检查
`check_readiness`	准备状态
`get_server_health`	详细的组件运行状况

健康状况值

状态	含义
`healthy`	所有组件就绪
`degraded`	某些组件是部分的，但可以运行
`unhealthy`	关键组件出现故障

发展

设置

# Clone and install
git clone https://github.com/your-org/naics-mcp-server.git
cd naics-mcp-server
pip install -e ".[dev]"

# Run tests
pytest

# Run tests with coverage
pytest --cov=naics_mcp_server --cov-report=term-missing

# Lint
ruff check naics_mcp_server/ tests/

# Format
ruff format naics_mcp_server/ tests/

# Type check
mypy naics_mcp_server/

项目结构

naics-mcp-server/
├── naics_mcp_server/
│   ├── __init__.py
│   ├── server.py           # MCP server and tools
│   ├── cli.py              # Command-line interface
│   ├── config.py           # Pydantic configuration
│   ├── core/
│   │   ├── database.py     # DuckDB operations
│   │   ├── embeddings.py   # Sentence transformers
│   │   ├── search_engine.py # Hybrid search
│   │   ├── health.py       # Health checks
│   │   ├── errors.py       # Error handling
│   │   └── validation.py   # Input validation
│   ├── models/
│   │   ├── naics_models.py # NAICS data models
│   │   └── search_models.py # Search result models
│   └── observability/
│       ├── logging.py      # Structured logging
│       └── audit.py        # Audit logging
├── tests/
├── data/                   # Pre-built DuckDB database (included)
├── Dockerfile
├── docker-compose.yml
└── pyproject.toml

建筑

数据流

User Query
    │
    ▼
┌─────────────────┐
│  Input Validation│
└────────┬────────┘
         │
         ▼
┌─────────────────┐
│  Query Expansion │ ─── Synonyms, stemming
└────────┬────────┘
         │
         ▼
┌─────────────────────────────────────────┐
│            Hybrid Search                 │
│  ┌─────────────┐    ┌─────────────┐     │
│  │  Semantic   │    │   Lexical   │     │
│  │  (70%)      │    │   (30%)     │     │
│  └──────┬──────┘    └──────┬──────┘     │
│         └────────┬─────────┘            │
└──────────────────┼──────────────────────┘
                   │
                   ▼
         ┌─────────────────┐
         │ Confidence Scoring│
         └────────┬────────┘
                  │
                  ▼
         ┌─────────────────┐
         │ Cross-Ref Check  │
         └────────┬────────┘
                  │
                  ▼
            Results

置信度评分

overall = (
    0.40 × semantic_score +     # Embedding similarity
    0.20 × lexical_score +      # Term overlap
    0.15 × index_term_match +   # Official index hit
    0.15 × specificity_bonus +  # 6-digit preferred
    0.10 × cross_ref_factor     # Classification guidance
)

数据库模式

-- NAICS codes (2,125 total across all levels)
naics_nodes (
    node_code VARCHAR PRIMARY KEY,
    level VARCHAR,              -- sector, subsector, etc.
    title VARCHAR,
    description TEXT,
    sector_code, subsector_code, industry_group_code, naics_industry_code,
    raw_embedding_text TEXT
)

-- Vector embeddings (384 dimensions)
naics_embeddings (node_code, embedding FLOAT[384], embedding_text)

-- Official index terms (20,398 entries)
naics_index_terms (term_id, naics_code, index_term, term_normalized)

-- Cross-references for classification guidance
naics_cross_references (
    ref_id, source_code, reference_type,
    reference_text, target_code, excluded_activity
)

演出

度量	目标	注释
搜索延迟（冷）	<200ms	第一次搜索
搜索延迟（热）	<50ms	缓存
批次（100个项目）	<10s	混合复杂性
服务器启动	<30s	包括模型加载
内存使用量	<1GB	稳态

数据源

文件	内容
`2-6 digit_2022_Codes.xlsx`	所有NAICS代码和标题
`2022_NAICS_Descriptions.xlsx`	完整的代码描述
`2022_NAICS_Index_File.xlsx`	20398官方索引术语
`2022_NAICS_Cross_References.xlsx`	分类指南

文档

文档	描述
api参考	完整的MCP工具参考
HTTP端点	健康检查和指标API
Kubernetes部署	Kubernetes部署指南
更新日志	版本历史
生产要求	生产准备检查表

许可证

MIT许可证-请参阅许可证了解详情。

贡献

欢迎投稿！请看贡献.md 作为指导方针。

使用说明

NAICS MCP服务器

特性

目录

快速开始

使用Docker（推荐）

使用pip

安装

来自PyPI

源自

具有发展依赖性

配置

核心设置

搜索设置

功能标志

日志记录

示例 .env 文件

码头工人

使用Docker Compose

发展模式

初始化数据库

塑造形象

Docker卷

Kubernetes

MCP工具

搜索工具

层次结构工具

分类工具

分析工具

工作簿工具

诊断工具

CLI使用情况

批次分类

健康检查

HTTP端点（端口9090）

MCP工具

健康状况值

发展

设置

项目结构

建筑

数据流

置信度评分

数据库模式

演出

数据源

文档

许可证

贡献

相关 MCP

AI持久记忆服务器

Zotero文献库搜索与阅读MCP服务

Qdrant向量搜索MCP服务器

本地LLM模型控制协议

文档搜索服务

Laravel文档聚合工具

示例 `.env` 文件