使用说明

dapr mcp

一个模型上下文协议（MCP）服务器，它将Dapr的微服务构建块作为AI代理的工具公开。

概述

dapr-mcp将AI代理与dapr强大的微服务API连接起来，实现：

状态管理：使用事务支持保存、检索和删除状态
发布/子消息：将事件发布到消息代理
服务调用：调用其他支持Dapr的服务
秘密管理：从配置的存储中安全访问机密
分布式锁定：协调共享资源的访问
绑定：与外部系统（数据库、队列等）交互
对话AI：通过Dapr将任务委派给外部LLM
密码学：加密和解密敏感数据

特性

完全开放遥测可观察性（跟踪、度量、日志）
OAuth2.0/OIDC和SPIFFE身份验证支持
Kubernetes就绪的健康端点
动态组件发现
AI代理的全面安全规则

安装

来源

go install github.com/dapr/dapr-mcp-server/cmd/dapr-mcp-server@latest

从发布

从下载预构建的二进制文件发布页面。

码头工人

docker pull ghcr.io/dapr/dapr-mcp-server:latest
docker run -p 8080:8080 ghcr.io/dapr/dapr-mcp-server:latest

快速开始

初始化Dapr：

dapr init

运行MCP服务器：

dapr run --app-id dapr-mcp-server --resources-path components -- dapr-mcp-server --http localhost:8080

将您的AI代理连接到 http://localhost:8080

工具状态

类别	工具	状态	注释
actors	invoke_actor_method	Beta	虚拟actor方法调用
绑定	invoke_output_binding	稳定	外部系统交互
对话	对话_with_llm	稳定	委托给外部llm
crypto	encrypt_data	实验	可能被某些模型阻止
crypto	decrypt_data	实验	可能被某些模型阻止
调用	invoke_service	Beta	服务来服务调用
lock	acquire_lock	稳定	分布式锁定
lock	release_lock	稳定	分布式锁定
元数据	组件	稳定	组件发现
pubsub	publish_event	稳定	事件发布
pubsub	publish_event_with_metata	稳定	带标头的事件发布
secrets	get_secret	稳定	单秘密检索
secrets	get_bulk_secrets	稳定	批量秘密检索
state	save_state	稳定	状态持久性
state	get_state	稳定	状态检索
state	delete_state	稳定	状态删除
state	execute_transaction	Stable	原子状态操作

配置

环境变量

核心配置

变量	描述	默认值
`DAPR_MCP_SERVER_LOG_LEVEL`	日志级别：调试、信息、警告、错误	`INFO`

开放遥测配置

变量	描述	默认值
`OTEL_EXPORTER_OTLP_ENDPOINT`	所有信号的OTLP端点	（无-禁用）
`OTEL_EXPORTER_OTLP_TRACES_ENDPOINT`	覆盖跟踪端点	使用 `OTEL_EXPORTER_OTLP_ENDPOINT`
`OTEL_EXPORTER_OTLP_METRICS_ENDPOINT`	指标端点的覆盖	使用 `OTEL_EXPORTER_OTLP_ENDPOINT`
`OTEL_EXPORTER_OTLP_LOGS_ENDPOINT`	日志端点的覆盖	使用 `OTEL_EXPORTER_OTLP_ENDPOINT`
`OTEL_EXPORTER_OTLP_PROTOCOL`	协议：grpc、http/protobuf	`grpc`
`OTEL_EXPORTER_OTLP_HEADERS`	标题（键=值，键2=值2）	（无）
`OTEL_SERVICE_NAME`	遥测服务名称	`dapr-mcp-server`
`OTEL_SERVICE_VERSION`	服务版本	`v1.0.0`
`DAPR_MCP_SERVER_METRICS_ENABLED`	启用指标导出	`true`
`DAPR_MCP_SERVER_LOGS_OTEL_ENABLED`	通过OTEL导出日志	`true`

验证配置

变量	描述	默认值
`AUTH_ENABLED`	启用身份验证	`false`
`AUTH_MODE`	模式：禁用、oidc、spiffe、dapr哨兵、混合动力	`disabled`
`AUTH_SKIP_PATHS`	跳过身份验证的路径（逗号分隔）	`/livez,/readyz,/startupz`

OIDC配置

变量	描述	默认值
`OIDC_ENABLED`	启用OIDC身份验证	`false`
`OIDC_ISSUER_URL`	OIDC提供程序URL	（如果启用了OIDC，则需要）
`OIDC_CLIENT_ID`	预期受众（aud声明）	（如果启用OIDC，则需要）
`OIDC_ALLOWED_ALGORITHMS`	允许的签名算法	`RS256,ES256`
`OIDC_SKIP_ISSUER_CHECK`	跳过发行者验证（仅限开发人员）	`false`

SPIFFE配置

变量	描述	默认值
`SPIFFE_ENABLED`	启用SPIFFE身份验证	`false`
`SPIFFE_TRUST_DOMAIN`	SPIFFE信任域	（如果启用SPIFFE，则需要）
`SPIFFE_SERVER_ID`	此服务器的SPIFFE ID	（如果启用了SPIFFE，则需要）
`SPIFFE_ENDPOINT_SOCKET`	工作负载API套接字路径	`SPIFFE_ENDPOINT_SOCKET` env
`SPIFFE_ALLOWED_CLIENTS`	允许的客户端SPIFFE ID	（无-全部允许）

Dapr哨兵配置

变量	描述	默认值
`DAPR_SENTRY_ENABLED`	启用Dapr Sentry身份验证	`false`
`DAPR_SENTRY_JWKS_URL`	Dapr Sentry JWKS端点	（如果启用，则需要）
`DAPR_SENTRY_TRUST_DOMAIN`	预期的SPIFFE信任域	（如果启用，则为必填项）
`DAPR_SENTRY_AUDIENCE`	预期受众声明	（无-未验证）
`DAPR_SENTRY_TOKEN_HEADER`	包含JWT的标题	`Authorization`
`DAPR_SENTRY_JWKS_REFRESH_INTERVAL`	JWKS缓存刷新间隔	`5m`

健康终点

Kubernetes兼容的健康端点：

终点	目的
`GET /livez`	Liveness探测器-服务器正在运行
`GET /readyz`	就绪探测-服务器可以接受流量
`GET /startupz`	启动探测-初始化完成

开放遥测

指标

度量	类型	描述
`dapr-mcp-server.tool.invocations`	计数器	工具调用总数
`dapr-mcp-server.tool.errors`	计数器	工具调用失败
`dapr-mcp-server.tool.duration`	柱状图	执行时间（ms）
`dapr-mcp-server.tool.in_progress`	UpDownCounter	当前正在执行的工具

跨度属性

每个工具跨度包括：

tool.name：正在调用的工具
tool.package：包含工具的包
dapr.operation：Dapr操作类型
dapr.component.type：使用的组件类型
outcome：成功或错误

示例：Jaeger设置

# Start Jaeger
docker run -d --name jaeger \
  -p 16686:16686 \
  -p 4317:4317 \
  jaegertracing/all-in-one:latest

# Configure dapr-mcp
export OTEL_EXPORTER_OTLP_ENDPOINT=http://localhost:4317
export OTEL_EXPORTER_OTLP_PROTOCOL=grpc

# Run server
dapr run --app-id dapr-mcp-server --resources-path components -- dapr-mcp-server --http localhost:8080

身份验证设置

OIDC（OAuth2.0）

export AUTH_ENABLED=true
export AUTH_MODE=oidc
export OIDC_ENABLED=true
export OIDC_ISSUER_URL=https://accounts.google.com
export OIDC_CLIENT_ID=your-client-id

史匹夫

export AUTH_ENABLED=true
export AUTH_MODE=spiffe
export SPIFFE_ENABLED=true
export SPIFFE_TRUST_DOMAIN=example.org
export SPIFFE_SERVER_ID=spiffe://example.org/dapr-mcp
export SPIFFE_ENDPOINT_SOCKET=unix:///tmp/spire-agent/public/api.sock

Dapr哨兵

对于使用Sentry但没有完整SPIRE基础设施的Dapr环境：

export AUTH_ENABLED=true
export AUTH_MODE=dapr-sentry
export DAPR_SENTRY_ENABLED=true
export DAPR_SENTRY_JWKS_URL=http://dapr-sentry:8080/jwks.json
export DAPR_SENTRY_TRUST_DOMAIN=public
export DAPR_SENTRY_AUDIENCE=public  # Optional

注： Dapr Sentry JWT在 sub 索赔但没有 iss 索赔，这就是为什么他们需要这个专用的认证器而不是OIDC。

混合模式

接受多种身份验证方法（OIDC、SPIFFE和/或Dapr Sentry）：

export AUTH_ENABLED=true
export AUTH_MODE=hybrid
export OIDC_ENABLED=true
export OIDC_ISSUER_URL=https://accounts.google.com
export OIDC_CLIENT_ID=your-client-id
export SPIFFE_ENABLED=true
export SPIFFE_TRUST_DOMAIN=example.org
export SPIFFE_SERVER_ID=spiffe://example.org/dapr-mcp
# Optionally add Dapr Sentry as well:
# export DAPR_SENTRY_ENABLED=true
# export DAPR_SENTRY_JWKS_URL=http://dapr-sentry:8080/jwks.json
# export DAPR_SENTRY_TRUST_DOMAIN=public

IDE集成

VS Code

添加 .vscode/mcp.json:

{
  "servers": {
    "dapr-mcp": {
      "type": "http",
      "url": "http://localhost:8080"
    }
  }
}

克劳德桌面版

添加到您的Claude Desktop配置中：

{
  "mcpServers": {
    "dapr-mcp": {
      "url": "http://localhost:8080"
    }
  }
}

发展

先决条件

转到1.21+
Dapr命令行界面
Docker（可选，用于本地测试）

建筑

go build -o dapr-mcp-server ./cmd/dapr-mcp-server

测试

go test -v -race ./...

代码检查

golangci-lint run

建筑

cmd/dapr-mcp-server/          # Main entry point
pkg/
  actors/             # Virtual actor tools
  auth/               # Authentication (OIDC, SPIFFE)
  bindings/           # Output binding tools
  conversation/       # LLM conversation tools
  crypto/             # Encryption/decryption tools
  health/             # Health check endpoints
  invoke/             # Service invocation tools
  lock/               # Distributed lock tools
  metadata/           # Component discovery
  mocks/              # Test mocks
  pubsub/             # Pub/Sub tools
  secrets/            # Secret management tools
  state/              # State management tools
  telemetry/          # OTEL instrumentation

贡献

欢迎投稿！拜托：

克隆该仓库
创建要素分支
通过测试进行更改
跑 golangci-lint run 和 go test ./...
提交拉取请求

许可证

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