Narsil MCP Docker

Narsil MCP服务器-Docker镜像

Unofficial Multi-Architecture Docker Image for Narsil MCP Server

概述

这是一个非官方的、由社区维护的Docker镜像，它打包了 Narsil MCP服务器 用于集装箱化部署。它使AI代理（Claude Code、VS Code Copilot、Cursor、Windsurf等）能够通过模型上下文协议（MCP）执行深度代码智能。

上游： （麻省理工学院或阿帕奇-2.0）

主要特点

• 多架构支持 -原生支持x86-64和ARM64
• 多种传输协议 -可流式传输的HTTP、SSE和WebSocket支持（可通过env-var选择）
• 90种代码智能工具 -符号搜索、调用图、安全分析、SBOM等
• 32语言支持 -Rust、Python、TypeScript、Go、Java、C#等26种语言
• 设计安全 -API密钥认证（不区分大小写的承载）、CORS、TLS终止、安全头
• 高性能 -HAProxy支持QUIC/HTTP3，ZSTD压缩

可用Narsil MCP工具类别

______________________________________________________________________

给我买杯咖啡

您的支持鼓励我继续创建/支持我的开源项目。 如果你在这个项目中发现了价值，你可以给我买杯咖啡，让我保持灵感。

快速开始

先决条件

• Docker引擎： 23.0+

关键： 在没有适当的安全措施（反向代理、SSL/TLS、身份验证、防火墙规则）的情况下，不要将此容器直接暴露在互联网上。

______________________________________________________________________

Docker Compose（推荐）

services:
  narsil-mcp:
    image: mekayelanik/narsil-mcp:latest
    container_name: narsil-mcp
    restart: unless-stopped
    ports:
      - "8010:8010"
      # Optional: HTTP visualization frontend (requires NARSIL_HTTP=true)
      # - "3000:3000"
    volumes:
      - /path/to/your/repos:/data:ro
      - narsil-cache:/home/node/.cache         # Persist embedding model cache
    environment:
      - PORT=8010
      - INTERNAL_PORT=38011
      - PUID=1000
      - PGID=1000
      - TZ=UTC
      - NODE_ENV=production
      - PROTOCOL=SHTTP
      - ENABLE_HTTPS=false
      - HTTP_VERSION_MODE=auto
      - DATA_DIR=/data
      - NARSIL_GIT=true
      - NARSIL_CALL_GRAPH=true
      - NARSIL_PERSIST=true
      - NARSIL_STREAMING=true
      # Optional: Neural semantic search
      # - NARSIL_NEURAL=true
      # - VOYAGE_API_KEY=your-voyage-key
      # Optional: HTTP visualization frontend
      # - NARSIL_HTTP=true
      # - NARSIL_HTTP_PORT=3000
      # Optional: require Bearer token auth at HAProxy layer
      # - API_KEY=replace-with-strong-secret
      # Optional: CORS origins
      # - CORS=*

volumes:
  narsil-cache:
    driver: local

Docker运行

docker volume create narsil-cache
docker run -d \
  --name=narsil-mcp \
  --restart=unless-stopped \
  -p 8010:8010 \
  -v /path/to/your/repos:/data:ro \
  -v narsil-cache:/home/node/.cache \
  -e PORT=8010 \
  -e PROTOCOL=SHTTP \
  -e NARSIL_GIT=true \
  -e NARSIL_CALL_GRAPH=true \
  -e NARSIL_PERSIST=true \
  mekayelanik/narsil-mcp:latest

# With HTTP visualization frontend enabled:
docker volume create narsil-cache
docker run -d \
  --name=narsil-mcp \
  --restart=unless-stopped \
  -p 8010:8010 \
  -p 3000:3000 \
  -v /path/to/your/repos:/data:ro \
  -v narsil-cache:/home/node/.cache \
  -e PORT=8010 \
  -e PROTOCOL=SHTTP \
  -e NARSIL_GIT=true \
  -e NARSIL_CALL_GRAPH=true \
  -e NARSIL_PERSIST=true \
  -e NARSIL_HTTP=true \
  mekayelanik/narsil-mcp:latest

访问端点

启用HTTPS时(ENABLE_HTTPS=true)，使用TLS端点：

安全警告： 容器默认为HTTP(ENABLE_HTTPS=false)以便于本地设置。使用 ENABLE_HTTPS=true 有自己的生产证书。看 证书_教程_指南.md 以获取说明。

______________________________________________________________________

配置

完整的环境变量参考

核心设置

Narsil MCP功能标志

Narsil MCP串设置

API密钥的神经嵌入

神经嵌入注释

神经嵌入是 可选的.没有 NARSIL_NEURAL=true，所有80多个核心工具都能工作（符号搜索、调用图、安全扫描、SBOM、git分析、类型推理、数据流、SPARQL等）。仅 neural_search 和 find_semantic_clones 需要嵌入。

• API后端 （默认）：设置 NARSIL_NEURAL=true + NARSIL_NEURAL_BACKEND=api +API密钥。默认型号为 voyage-code-2 （1024调暗）。
• ONNX后端 （本地，无API密钥）：设置 NARSIL_NEURAL_BACKEND=onnx。需要通过手动下载模型 optimum-cli export onnx。不自动下载。
• 缓存持久性：The narsil-cache 体积在 /home/node/.cache 在重新启动时持久化模型文件和ONNX缓存。

API后端示例：

# Voyage AI
- NARSIL_NEURAL=true
- NARSIL_NEURAL_BACKEND=api
- NARSIL_NEURAL_MODEL=voyage-code-2
- VOYAGE_API_KEY=your-voyage-key

# OpenAI
- NARSIL_NEURAL=true
- NARSIL_NEURAL_BACKEND=api
- NARSIL_NEURAL_MODEL=text-embedding-3-small
- OPENAI_API_KEY=sk-your-key

# Custom OpenAI-compatible endpoint (e.g., self-hosted embedding server)
- NARSIL_NEURAL=true
- NARSIL_NEURAL_BACKEND=api
- NARSIL_NEURAL_MODEL=Snowflake/snowflake-arctic-embed-xs
- EMBEDDING_SERVER_ENDPOINT=http://your-embedder-host:port/v1
- EMBEDDING_API_KEY=your-key-or-unused
- NARSIL_NEURAL_DIMENSION=384

Narsil MCP预设

安全设置

布尔值： true, 1, yes, on 都被视为真理。其他一切都是假的。

每个容器生命周期一次： NARSIL_REINDEX 容器创建后只运行一次。在后续重启时跳过它（例如， docker restart).要重新触发，请重新创建容器(docker compose down && docker compose up -d).

健康检查： 容器的健康检查有60秒的启动期，以适应缓慢的启动，尤其是在 NARSIL_REINDEX=true 或 NARSIL_NEURAL=true 触发初始索引或模型加载。

API密钥验证说明

• 集 API_KEY 在反向代理级别强制执行身份验证。
• 头球 Authorization: Bearer .
• /healthz CORS飞行前（OPTIONS）绕过身份验证。

速率限制和IP访问控制

• 速率限制： 集 RATE_LIMIT=100 允许每100个请求 RATE_LIMIT_PERIOD （默认值 10s)每个IP。超过限制将返回HTTP 429 Retry-After 头球
• 连接限制： 集 MAX_CONNECTIONS_PER_IP=50 限制每个IP的并发连接。超过此值将返回HTTP 429。
• IP阻止列表： 集 IP_BLOCKLIST=192.0.2.0/24,198.51.100.5 以阻止特定IP/CIDR。被阻止的IP接收HTTP 403。
• IP地址列表： 集 IP_ALLOWLIST=10.0.0.0/8,192.168.1.0/24 只允许列出的IP/CIDR。所有其他人都接收HTTP 403。始终允许本地主机。
• 所有功能默认为禁用。根据需要进行组合——在分配列表之前检查块列表。

一次性操作

对于不设置环境变量的ad-hoc操作，请使用 docker exec:

docker exec narsil-mcp narsil-mcp --repos /data --reindex   # Force full re-index

______________________________________________________________________

安装分析存储库

将存储库目录装载到 /data （或指定的路径 DATA_DIR).每个子目录都成为一个可索引的存储库。

volumes:
  # Mount entire projects directory
  - /home/user/projects:/data:ro
  # Or mount individual repositories
  - /home/user/my-rust-app:/data/my-rust-app:ro
  - /home/user/my-node-app:/data/my-node-app:ro

然后告诉你的AI代理使用挂载的路径进行分析：

• “在中搜索符号 /data/my-rust-app"
• “在中查找注入漏洞 /data/my-node-app"
• “为生成SBOM /data/my-rust-app"
• “获取调用图 main 在 /data/my-node-app"

______________________________________________________________________

MCP客户端配置

克劳德代码

添加 ~/.claude.json 在...之下 mcpServers:

{
  "mcpServers": {
    "narsil": {
      "type": "sse",
      "url": "http://host-ip:8010/sse"
    }
  }
}

或者对于流式HTTP：

{
  "mcpServers": {
    "narsil": {
      "type": "http",
      "url": "http://host-ip:8010/mcp"
    }
  }
}

VS代码/代码/光标/风帆

它们都使用相同的JSON格式。在相应的配置文件中进行配置：

• VS Code: .vscode/settings.json （按键： mcp.servers)
• 法典: ~/.codex/config.json （按键： mcpServers)
• 光标: ~/.cursor/mcp.json （按键： mcpServers)
• 帆板运动: .codeium/mcp_settings.json （按键： mcpServers)

{
  "mcpServers": {
    "narsil": {
      "transport": "http",
      "url": "http://host-ip:8010/mcp"
    }
  }
}

______________________________________________________________________

可用标签

______________________________________________________________________

许可证

此Docker镜像打包已获得许可 GNU通用公共许可证v3.0.

上游许可证

• 超级网关：MIT许可证
• HAProxy：GNU通用公共许可证v2.0

这是一个 非官方的 社区包装。它不隶属于narsil-mcp作者，也不受其认可或支持。看 通知 以获得完整的归属。

______________________________________________________________________

给我买杯咖啡

您的支持鼓励我继续创建/支持我的开源项目。 如果你在这个项目中发现了价值，你可以给我买杯咖啡，让我保持灵感。

______________________________________________________________________

维护者

穆罕默德·梅凯埃尔·阿尼克

• Docker Hub： 梅凯耶兰尼克
• github： 梅凯埃尔·阿尼克