使用说明

数字银行弹性MCP服务器

stdio 模型上下文协议（MCP）Elasticsearch服务器，具有多阶段PII编辑功能，适用于金融机构或受监管环境。专为数字银行团队打造，业务经理、架构师和开发人员需要对话式访问运营数据，而无需手动编写KQL或Elasticsearch DSL。

1.为什么存在

数字银行部落掌握着大量的遥测数据：支付轨道（SWIFT gpi、SEPA）、客户会话数据、APM跟踪和微服务日志。今天查询这些数据需要掌握Elasticsearch DSL或依赖可能无法回答特定问题的预构建仪表板。

此MCP服务器弥合了这一差距。它允许LLM代理发现您的集群、理解索引结构、执行只读查询和检查平台健康状况——所有这些都是通过一个安全、经过审计的管道完成的，该管道在数据离开您的基础设施之前对PII进行编辑。

Persona	他们得到了什么
业务经理	询问有关交易量、入职渠道或流动性指标的自然语言问题。代理为您构建DSL查询。
软件架构师	探索集群拓扑结构，查看索引映射，并在不切换到外部仪表板的情况下评估系统健康状况。
开发者	通过跨微服务关联日志进行调试。通过对话方式搜索错误模式、跟踪事务ID并检查警报规则。

2.特点

群集发现 --自动发现索引、字段映射和文档计数，以便代理在查询之前知道哪些数据可用。
只读搜索 --执行带有强制只读防护栏的Elasticsearch DSL查询。被屏蔽的关键字(_update, _delete, _bulk, script)在输入净化层被拒绝。
群集运行状况 --返回总体集群状态（绿色/黄色/红色）、节点计数、分片计数以及集群、索引或分片粒度的未分配分片详细信息。
警报状态 --检索Kibana警报规则及其上次执行状态，支持按规则类型、严重性标记和执行状态进行筛选（需要可选 KIBANA_URL).
时间范围过滤 --自然时间表达式(now-24h, now-7d)自动合并到任何查询形状（bool、simple或空）中。
PII补救措施 --信用卡（Luhn验证）、IBAN、SSN、电子邮件和电话号码在结果到达LLM之前被屏蔽。PCI DSS和GDPR合规性的深度防御。
审计日志 --每次工具调用都会记录到stderr中，包括工具名称、参数、执行时间、编校计数和错误详细信息。
索引访问控制 --限制代理可以通过哪些索引进行触摸 ALLOWED_INDEX_PATTERNS.
使用回退重试 --使用指数回退重试瞬态故障（429503，网络错误）。

3.建筑

┌─────────────┐     stdio / SSE      ┌──────────────────────┐
│  LLM Agent  │ ◄──────────────────► │   MCP Server         │
│  (Claude,   │                      │                      │
│   GPT, etc) │                      │  ┌────────────────┐  │
└─────────────┘                      │  │ Input Sanitizer │  │
                                     │  └───────┬────────┘  │
                                     │          ▼           │
                                     │  ┌────────────────┐  │
                                     │  │  Tool Execute   │  │
                                     │  └───────┬────────┘  │
                                     │          ▼           │
                                     │  ┌────────────────┐  │
                                     │  │ PII Redaction   │  │
                                     │  └───────┬────────┘  │
                                     │          ▼           │
                                     │  ┌────────────────┐  │
                                     │  │ Audit Logger    │  │
                                     │  └────────────────┘  │
                                     └──────────┬───────────┘
                                                │
                                                ▼
                                     ┌──────────────────────┐
                                     │  Elasticsearch        │
                                     │  Cluster              │
                                     └──────────────────────┘

每个工具调用都通过一个安全的管道进行： 验证输入 → 执行查询 → 编辑个人身份信息 → 日志审核条目 → 返回结果。此管道一次性实施 createSecureTool 并由所有工具共享。

4.快速入门

先决条件

Node.js 18+
Elasticsearch部署（弹性云或自托管）
对要公开的索引具有只读权限的API密钥
与Elasticsearch兼容<8.18（在8.18中引入内置MCP构建器功能之前）

安装和构建

git clone <this-repo>
cd financial-elastic-mcp-server
npm install
npm run build:mcp

配置

创建一个 .env 文件或导出环境变量：

# Required
export ELASTIC_URL="https://your-deployment.es.us-east-1.aws.found.io"
export ELASTIC_API_KEY="your-base64-encoded-api-key"

# Optional — set to enable Kibana-specific features (e.g., get_alert_status)
export KIBANA_URL="https://your-deployment.kb.us-east-1.aws.found.io"

# Optional
export ALLOWED_INDEX_PATTERNS="logs-*,transactions-*"  # Comma-separated. Empty = all indices.
export MAX_SEARCH_SIZE="100"                            # Max docs per search (1-500, default 100)
export REQUEST_TIMEOUT_MS="30000"                       # HTTP timeout (default 30s)
export RETRY_ATTEMPTS="3"                               # Retry count for transient failures
export RETRY_DELAY_MS="1000"                            # Base delay for exponential backoff
export KIBANA_SPACE=""                                  # Kibana space (empty = default space)
export AUDIT_ENABLED="true"                             # Audit logging to stderr (default true)
export PII_REDACTION_ENABLED="true"                     # PII masking (default true)

跑

node dist/stdio.mjs

连接到克劳德桌面

添加到您的 claude_desktop_config.json:

{
  "mcpServers": {
    "elastic": {
      "command": "node",
      "args": ["/absolute/path/to/dist/stdio.mjs"],
      "env": {
        "ELASTIC_URL": "https://your-deployment.es.us-east-1.aws.found.io",
        "ELASTIC_API_KEY": "your-api-key"
      }
    }
  }
}

5.工具参考

`discover_cluster`

从这里开始。 发现所有可用索引及其字段映射。在构造查询之前，代理应首先调用此函数以了解存在哪些数据。

参数	类型	默认值	说明
`pattern`	字符串	`*`	索引模式过滤器（例如。， `logs-*`)
`include_hidden`	布尔值	`false`	包括系统指标(`.kibana`等等）
`max_indices`	编号	`50`	获取映射的索引上限

返回按文档计数排序的索引（最大的第一个），每个索引都有一个简单的列表 { field, type } 映射。

`elastic_search`

对Elasticsearch索引执行只读ElasticsearchDSL查询。

参数	类型	默认值	说明
`index`	字符串	必需的	要搜索的索引模式（例如。， `transactions-*`)
`query`	对象	必需的	Elasticsearch DSL查询体
`size`	编号	`10`	返回结果（上限为 `MAX_SEARCH_SIZE`)
`time_range`	string	--	时间过滤器表达式（例如。， `now-24h`, `now-7d`)

这 time_range 参数会自动合并到您提供的任何查询形状中——布尔查询、简单查询或空查询都可以。

`check_cluster_health`

返回Elasticsearch集群的运行状况。使用此功能诊断降级或红色集群，并在调查查询或性能问题之前验证平台运行状况。

参数	类型	默认值	说明
`level`	enum	`"cluster"`	粒度： `"cluster"`, `"indices"`，或 `"shards"`更高级别包括每个索引或每个分片的详细信息。

退货 status （绿色/黄色/红色）、节点计数、分片计数和 unassigned_shards.

`get_alert_status`

检索Kibana警报规则及其上次执行状态。需要 KIBANA_URL 待配置。在调查事件时使用此功能来识别火灾或错误警报。如果出现以下情况，则返回一条优雅的错误消息 KIBANA_URL 未设置或Kibana警报插件未启用。

参数	类型	默认值	说明
`severity`	string	--	按严重性标签过滤（例如。， `"critical"`, `"warning"`)
`rule_type`	string	--	按规则类型ID过滤（例如。， `".es-query"`, `"apm.error_rate"`)
`status`	enum	--	客户端筛选器： `"active"`, `"inactive"`, `"error"`，或 `"ok"`
`max_results`	编号	`20`	要返回的最大规则数

6.提示和资源

服务器暴露MCP 提示（指导工作流程）和资源（静态参考文档）及其工具。

提示提供LLM可以遵循的分步调查工作流程：

提示	目的
`investigate_failed_transactions`	Elasticsearch中诊断支付失败的指导性工作流程
`compliance_audit_query`	构建PCI DSS/AML审计查询的结构化方法
`performance_investigation`	逐步调查延迟或吞吐量回归

资源 LLM可以阅读的静态参考文件：

资源	目的
`banking_query_patterns`	银行数据的常见Elasticsearch查询模式
`elasticsearch_best_practices`	查询优化和索引卫生指南
`banking_domain_glossary`	域术语的定义（SWIFT、SEPA、IBAN、流动性等）

7.安全与合规

此服务器专为受监管的环境而设计。多个防御层确保敏感数据永远不会在不受保护的情况下到达LLM。

PII补救措施

所有工具响应在离开服务器之前都会经过编校层。检测并屏蔽以下模式：

数据类型	示例输入	屏蔽输出
信用卡	`4111 1111 1111 1111`	`** ** 1111`
伊班	`DE89370400440532013000`	`DE89****3000`
SSN	`123-45-6789`	`*--****`
电子邮件	`john.doe@bank.com`	`j***@bank.com`
电话	`+1 555-123-4567`	`+15***67`

信用卡检测使用Luhn验证来避免随机16位数字的误报。

输入消毒

每个查询在执行前都会扫描危险关键字：

script, _update, _delete, _bulk, ctx._source

索引名称根据严格的正则表达式进行验证([a-zA-Z0-9\-.*,_]+)以防止注射。

索引访问控制

集 ALLOWED_INDEX_PATTERNS 以限制代理可以查询哪些索引。设置后，将拒绝对这些模式之外的索引的任何请求。这强制执行 最小特权原则 在MCP层，补充了Elastic的原生RBAC。

审计跟踪

每次工具调用都会向stderr生成一个结构化的JSON日志条目：

{
  "timestamp": "2026-02-15T10:30:00.000Z",
  "tool_called": "elastic_search",
  "input_parameters": "{\"index\":\"transactions-*\",...}",
  "output_size_bytes": 4521,
  "redaction_count": 3,
  "redacted_types": ["credit_card", "email"],
  "execution_time_ms": 245,
  "status": "success"
}

输入参数被截断为500个字符，以防止敏感数据泄露到日志中。

8.类型系统

工具结果使用不匹配区分类型安全模式匹配的联合：

import type { Model } from 'dismatch';

type ToolResult<T> = ToolSuccess<T> | ToolError;
type ToolSuccess<T> = Model<
  'success',
  { data: T; total?: number; aggregations?: Record<string, any> }
>;
type ToolError = Model<'error', { error: string }>;

这 type 现场('success' | 'error')是判别式。工具结果上的所有分支都使用 match() 从dismatch到详尽的编译时检查模式匹配——否 if/else 链条或 switch 声明。

9.测试

单元和集成测试

服务器附带了一个基于 Vitest.测试与其模块位于同一地点 __tests__/ 目录。

npm test

单元测试 单独覆盖单个库模块：

模块	测试内容
`piiRedaction`	模式检测精度、Luhn验证、掩蔽格式
`inputSanitizer`	阻止关键字检测、索引名称验证
`mappingUtils`	字段扁平化、多字段扩展、重复数据删除
`auditLogger`	日志格式、截断、stderr路由

集成测试 端到端练习完整的工具执行管道（输入→ 执行→ 个人身份信息脱敏→ 结果），HTTP层被mock-fns替换：

工具/模块	涵盖的关键场景
`discoverCluster`	索引发现、隐藏索引过滤、映射获取失败
`checkClusterHealth`	集群/索引/分片级输出，参数传递
`getAlertStatus`	规则规范化、KQL过滤器构建、404/403优雅错误
`prompts`	快速注册、参数模式、模板呈现
`resources`	资源注册、URI解析、内容完整性

所有82项测试都通过了当前版本。

手动重动作演示

scripts/test-redaction.ts 是一个自包含的脚本，它针对真实的事务日志负载运行编校引擎，因此您可以在没有Elasticsearch集群的情况下直观地验证掩码格式和准确性。

# Stage 1 only — no AWS credentials needed
npm run test:redaction

# Both stages — requires AWS credentials and Comprehend access
npm run test:redaction -- --comprehend

第1阶段 （正则表达式，始终运行）包括：

PII类型	示例输入	屏蔽输出	注释
信用卡	`4111 1111 1111 1111`	`** ** 1111`	Luhn验证；失败的Luhn数保持不变
伊班	`DE89370400440532013000`	`DE89****3000`
SSN	`123-45-6789`	`*--****`
电子邮件	`john.doe@bank.com`	`j***@bank.com`
电话	`+31 6 1234 5678`	`+31***78`

第2阶段 (--comprehend)在第一阶段输出的基础上添加AWS Comprehend NER，捕获正则表达式无法捕获的上下文PII：

PII类型	示例输入	屏蔽输出
全名	`John Doe`	`[REDACTED:NAME]`
街道地址	`42 Main Street, Amsterdam`	`[REDACTED:ADDRESS]`
IP地址	`192.168.1.101`	`[REDACTED:IP_ADDRESS]`

脚本在每个阶段后打印摘要，显示 redactionCount 和 redactedTypes，并明确确认无效的Luhn卡号保持不变。

10.项目结构

src/
├── lib/
│   ├── types.ts                    # ToolResult<T> discriminated union
│   ├── config.ts                   # Environment-based configuration loader
│   ├── esClient.ts                 # Elasticsearch/Kibana HTTP client with retry
│   ├── toolWrapper.ts              # Secure tool pipeline (sanitize → execute → redact → audit)
│   ├── piiRedaction.ts             # Regex-based PII detection and masking
│   ├── inputSanitizer.ts           # Query validation and index name sanitization
│   ├── auditLogger.ts              # Structured audit logging to stderr
│   ├── mappingUtils.ts             # Elasticsearch mapping flattener
│   └── __tests__/                  # Unit tests for lib modules
├── tools/
│   ├── index.ts                    # Tool registry
│   ├── discoverCluster.ts          # discover_cluster tool
│   ├── elasticSearch.ts            # elastic_search tool
│   ├── checkClusterHealth.ts       # check_cluster_health tool
│   ├── getAlertStatus.ts           # get_alert_status tool
│   └── __tests__/                  # Integration tests for tools
├── prompts/
│   ├── index.ts                    # Prompt registry
│   ├── investigateFailedTransactions.ts
│   ├── complianceAuditQuery.ts
│   ├── performanceInvestigation.ts
│   └── __tests__/
├── resources/
│   ├── index.ts                    # Resource registry
│   ├── bankingQueryPatterns.ts
│   ├── elasticsearchBestPractices.ts
│   ├── bankingDomainGlossary.ts
│   └── __tests__/
└── mastra/
    └── stdio.ts                    # MCP server entry point (stdio transport)
scripts/
└── test-redaction.ts               # Manual PII redaction demo (Stage 1 + optional Stage 2)

11.路线图

此仓库-弹性<v8.18兼容性

Elastic v8.18引入了原生 MCP构建器它将Elasticsearch直接暴露给LLM，而无需自定义服务器。对于已经使用v8.18+的团队来说，该功能涵盖了此仓库提供的大部分内容。

因此，此回购的范围为 v8.18以下的Elasticsearch部署 --自托管集群、弹性云层或尚无法升级的气隙环境。它将保持在维护模式：错误修复、依赖关系更新和下面未完成的清理项目。这里没有计划使用主要的新工具。

新回购-- `elastic-pii-proxy`

Elastic的原生MCP服务器（v8.18+）功能强大，但没有内置的PII编辑或合规控制，这使得它不适合开箱即用的受监管环境。

配套项目将是 轻量级MCP代理 它位于Elastic的官方MCP服务器和LLM或运营商之间：

┌─────────────┐     MCP      ┌──────────────────┐     MCP      ┌─────────────────────┐
│  LLM Agent  │ ◄──────────► │ elastic-pii-proxy │ ◄──────────► │ Elastic MCP (v8.18+)│
│  (Claude,   │              │                  │              │                     │
│   GPT, etc) │              │  PII Redaction   │              │  Native Elastic MCP │
└─────────────┘              │  Audit Logging   │              └─────────────────────┘
                             │  GDPR/DORA/CCPA  │
                             └──────────────────┘

代理拦截来自Elastic的MCP响应，运行编校管道，发出合规性审计跟踪，并将经过净化的结果转发给LLM，而不需要对Elastic部署本身进行任何更改。

计划能力：

透明MCP代理——上游Elastic MCP配置不变
从该仓库继承的多阶段PII编辑（正则表达式+AWS Comprehend NER）
可配置的合规性配置文件（GDPR、DORA、CCPA字段级规则）
带有编辑计数和字段来源的结构化审计日志
零信任态度：没有原始个人身份信息能够到达LLM

12.许可证

MIT——免费使用、修改和分发。