Naics MCP Server

NAICS MCP服务器

  

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

特性

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

目录

• 快速开始
• 安装
• 配置
• 码头工人
• MCP工具
• CLI使用情况
• 健康检查
• 发展
• 建筑
• 许可证

快速开始

使用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]"

配置

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

核心设置

搜索设置

功能标志

日志记录

示例 .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卷

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工具

搜索工具

层次结构工具

分类工具

分析工具

工作簿工具

诊断工具

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

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

健康检查

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

HTTP端点（端口9090）

# 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工具

健康状况值

发展

设置

# 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
)

演出

数据源

文档

许可证

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

贡献

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