数字银行弹性MCP服务器
stdio 模型上下文协议 （MCP）Elasticsearch服务器，具有多阶段PII编辑功能，适用于金融机构或受监管环境。专为数字银行团队打造，业务经理、架构师和开发人员需要对话式访问运营数据，而无需手动编写KQL或Elasticsearch DSL。
______________________________________________________________________
目录
- 先决条件 - 安装和构建 - 配置 - 跑 - 连接到克劳德桌面
- discover_cluster - 弹性搜索 - 检查集群健康状况 - 获取警报状态
- PII补救措施 - 输入消毒 - 索引访问控制 - 审计跟踪
______________________________________________________________________
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兼容\
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.类型系统
工具结果使用 [不匹配](https://www.npmjs.com/package/dismatch) 区分类型安全模式匹配的联合：
import type { Model } from 'dismatch';
type ToolResult = ToolSuccess | ToolError; type ToolSuccess = Model }
;
type ToolError = Model;
这 `type` 现场(`'success'` | `'error'`)是判别式。工具结果上的所有分支都使用 `match()` 从dismatch到详尽的编译时检查模式匹配——否 `if/else` 链条或 `switch` 声明。
______________________________________________________________________
## 9.测试
### 单元和集成测试
服务器附带了一个基于 [Vitest](https://vitest.dev/).测试与其模块位于同一地点 `__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 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构建器](https://www.elastic.co/guide/en/kibana/current/mcp.html) 它将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——免费使用、修改和分发。