add mcp (Model Context Protocol) support

This commit is contained in:
MaysWind
2025-07-06 03:02:19 +08:00
parent 620ccf317f
commit 8dce0f2d6a
32 changed files with 1379 additions and 20 deletions
+12
View File
@@ -0,0 +1,12 @@
package mcp
var mcpTextContentTools = map[string]MCPToolHandler[MCPTextContent]{
"query_latest_exchange_rates": MCPQueryLatestExchangeRatesRequestToolHandler,
}
var mcpImageContentTools = map[string]MCPToolHandler[MCPImageContent]{}
var mcpAudioContentTools = map[string]MCPToolHandler[MCPAudioContent]{}
var mcpResourceLinkTools = map[string]MCPToolHandler[MCPResourceLink]{}
var mcpEmbeddedResourceTools = map[string]MCPToolHandler[MCPEmbeddedResource]{}
var AllMCPToolInfos = GetAllMCPToolInfos()
+124
View File
@@ -0,0 +1,124 @@
package mcp
import (
"encoding/json"
"reflect"
"strings"
"time"
"github.com/mayswind/ezbookkeeping/pkg/core"
"github.com/mayswind/ezbookkeeping/pkg/errs"
"github.com/mayswind/ezbookkeeping/pkg/exchangerates"
"github.com/mayswind/ezbookkeeping/pkg/models"
"github.com/mayswind/ezbookkeeping/pkg/settings"
"github.com/mayswind/ezbookkeeping/pkg/utils"
)
// MCPQueryExchangeRatesRequest represents all parameters of the query exchange rates request
type MCPQueryExchangeRatesRequest struct {
Currencies string `json:"currencies" jsonschema:"required,description=Comma-separated list of currencies to query exchange rates for (e.g. USD,CNY,EUR)"`
}
// MCPQueryExchangeRatesResponse represents the response structure for querying exchange rates
type MCPQueryExchangeRatesResponse struct {
BaseCurrency string `json:"base_currency" jsonschema_description:"Base currency code (e.g. USD)"`
UpdateTime string `json:"update_time" jsonschema_description:"Last update time of the exchange rates in RFC 3339 format (e.g. '2023-01-01T12:00:00Z')"`
Rates []*MCPQueryExchangeRateInfo `json:"rates" jsonschema_description:"Exchange rates for the specified currencies"`
}
// MCPQueryExchangeRateInfo defines the structure of exchange rate information for a specific currency
type MCPQueryExchangeRateInfo struct {
Currency string `json:"currency" jsonschema_description:"Currency code (e.g. USD)"`
Rate string `json:"rate" jsonschema_description:"The amount of the base currency that can be exchanged for 1 of this currency"`
}
type mcpQueryLatestExchangeRatesRequestToolHandler struct{}
var MCPQueryLatestExchangeRatesRequestToolHandler = &mcpQueryLatestExchangeRatesRequestToolHandler{}
// Description returns the description of the MCP tool
func (h *mcpQueryLatestExchangeRatesRequestToolHandler) Description() string {
return "Query latest exchange rates with specified currencies."
}
// InputType returns the input type for the MCP tool request
func (h *mcpQueryLatestExchangeRatesRequestToolHandler) InputType() reflect.Type {
return reflect.TypeOf(&MCPQueryExchangeRatesRequest{})
}
// OutputType returns the output type for the MCP tool response
func (h *mcpQueryLatestExchangeRatesRequestToolHandler) OutputType() reflect.Type {
return reflect.TypeOf(&MCPQueryExchangeRatesResponse{})
}
// Handle processes the MCP call tool request and returns the response
func (h *mcpQueryLatestExchangeRatesRequestToolHandler) Handle(c *core.WebContext, callToolReq *MCPCallToolRequest, currentConfig *settings.Config, services MCPAvailableServices) ([]*MCPTextContent, *errs.Error) {
var exchangeRatesRequest MCPQueryExchangeRatesRequest
if callToolReq.Arguments != nil {
if err := json.Unmarshal(callToolReq.Arguments, &exchangeRatesRequest); err != nil {
return nil, errs.NewIncompleteOrIncorrectSubmissionError(err)
}
} else {
return nil, errs.ErrIncompleteOrIncorrectSubmission
}
dataSource := exchangerates.Container.Current
if dataSource == nil {
return nil, errs.ErrInvalidExchangeRatesDataSource
}
exchangeRateResponse, err := dataSource.GetLatestExchangeRates(c, c.GetCurrentUid(), currentConfig)
if err != nil {
return nil, errs.Or(err, errs.ErrOperationFailed)
}
response, err := h.createNewMCPQueryExchangeRatesResponse(exchangeRatesRequest.Currencies, exchangeRateResponse)
if err != nil {
return nil, errs.Or(err, errs.ErrOperationFailed)
}
return response, nil
}
func (h *mcpQueryLatestExchangeRatesRequestToolHandler) createNewMCPQueryExchangeRatesResponse(currencies string, exchangeRatesResp *models.LatestExchangeRateResponse) ([]*MCPTextContent, error) {
queryCurrencies := make(map[string]bool)
for _, currency := range strings.Split(currencies, ",") {
currency = strings.TrimSpace(currency)
if currency != "" {
queryCurrencies[currency] = true
}
}
response := &MCPQueryExchangeRatesResponse{
BaseCurrency: exchangeRatesResp.BaseCurrency,
UpdateTime: utils.FormatUnixTimeToLongDateTimeWithTimezoneRFC3389Format(exchangeRatesResp.UpdateTime, time.UTC),
Rates: make([]*MCPQueryExchangeRateInfo, 0, len(exchangeRatesResp.ExchangeRates)),
}
for _, rate := range exchangeRatesResp.ExchangeRates {
if _, exists := queryCurrencies[rate.Currency]; rate.Currency != exchangeRatesResp.BaseCurrency && !exists {
continue
}
response.Rates = append(response.Rates, &MCPQueryExchangeRateInfo{
Currency: rate.Currency,
Rate: rate.Rate,
})
}
content, err := json.Marshal(response)
if err != nil {
return nil, err
}
return []*MCPTextContent{
NewMCPTextContent(string(content)),
}, nil
}
+187
View File
@@ -0,0 +1,187 @@
package mcp
import (
"reflect"
"github.com/invopop/jsonschema"
"github.com/mayswind/ezbookkeeping/pkg/core"
"github.com/mayswind/ezbookkeeping/pkg/errs"
"github.com/mayswind/ezbookkeeping/pkg/services"
"github.com/mayswind/ezbookkeeping/pkg/settings"
)
// MCPAvailableServices holds the services available for MCP tools
type MCPAvailableServices interface {
GetTransactionService() *services.TransactionService
GetTransactionCategoryService() *services.TransactionCategoryService
GetTransactionTagService() *services.TransactionTagService
GetAccountService() *services.AccountService
GetUserService() *services.UserService
}
// MCPToolHandler defines the MCP tool handler
type MCPToolHandler[T MCPTextContent | MCPImageContent | MCPAudioContent | MCPResourceLink | MCPEmbeddedResource] interface {
// Description returns the description of the MCP tool
Description() string
// InputType returns the input type for the MCP tool request
InputType() reflect.Type
// OutputType returns the output type for the MCP tool response
OutputType() reflect.Type
// Handle processes the MCP call tool request and returns the response
Handle(*core.WebContext, *MCPCallToolRequest, *settings.Config, MCPAvailableServices) ([]*T, *errs.Error)
}
// GetAllMCPToolInfos returns all available MCP tool information
func GetAllMCPToolInfos() []*MCPTool {
toolInfos := make([]*MCPTool, 0)
for name, handler := range mcpTextContentTools {
toolInfos = append(toolInfos, getMCPToolInfo(name, handler))
}
for name, handler := range mcpImageContentTools {
toolInfos = append(toolInfos, getMCPToolInfo(name, handler))
}
for name, handler := range mcpAudioContentTools {
toolInfos = append(toolInfos, getMCPToolInfo(name, handler))
}
for name, handler := range mcpResourceLinkTools {
toolInfos = append(toolInfos, getMCPToolInfo(name, handler))
}
for name, handler := range mcpEmbeddedResourceTools {
toolInfos = append(toolInfos, getMCPToolInfo(name, handler))
}
return toolInfos
}
// MCPToolHandle handles the MCP tool request based on the tool name
func MCPToolHandle(c *core.WebContext, callToolReq *MCPCallToolRequest, currentConfig *settings.Config, services MCPAvailableServices) (any, *errs.Error) {
if handler, exists := mcpTextContentTools[callToolReq.Name]; exists {
return mcpTextContentToolHandle(c, handler, currentConfig, services, callToolReq)
}
if handler, exists := mcpImageContentTools[callToolReq.Name]; exists {
return mcpImageContentToolHandle(c, handler, currentConfig, services, callToolReq)
}
if handler, exists := mcpAudioContentTools[callToolReq.Name]; exists {
return mcpAudioContentToolHandle(c, handler, currentConfig, services, callToolReq)
}
if handler, exists := mcpResourceLinkTools[callToolReq.Name]; exists {
return mcpResourceLinkToolHandle(c, handler, currentConfig, services, callToolReq)
}
if handler, exists := mcpEmbeddedResourceTools[callToolReq.Name]; exists {
return mcpEmbeddedResourceToolHandle(c, handler, currentConfig, services, callToolReq)
}
return nil, errs.ErrApiNotFound
}
func mcpTextContentToolHandle(c *core.WebContext, handler MCPToolHandler[MCPTextContent], currentConfig *settings.Config, services MCPAvailableServices, callToolReq *MCPCallToolRequest) (any, *errs.Error) {
result, err := handler.Handle(c, callToolReq, currentConfig, services)
if err != nil {
return nil, errs.Or(err, errs.ErrOperationFailed)
}
callToolResp := MCPCallToolResponse[MCPTextContent]{
Content: result,
IsError: false,
}
return callToolResp, nil
}
func mcpImageContentToolHandle(c *core.WebContext, handler MCPToolHandler[MCPImageContent], currentConfig *settings.Config, services MCPAvailableServices, callToolReq *MCPCallToolRequest) (any, *errs.Error) {
result, err := handler.Handle(c, callToolReq, currentConfig, services)
if err != nil {
return nil, errs.Or(err, errs.ErrOperationFailed)
}
callToolResp := MCPCallToolResponse[MCPImageContent]{
Content: result,
IsError: false,
}
return callToolResp, nil
}
func mcpAudioContentToolHandle(c *core.WebContext, handler MCPToolHandler[MCPAudioContent], currentConfig *settings.Config, services MCPAvailableServices, callToolReq *MCPCallToolRequest) (any, *errs.Error) {
result, err := handler.Handle(c, callToolReq, currentConfig, services)
if err != nil {
return nil, errs.Or(err, errs.ErrOperationFailed)
}
callToolResp := MCPCallToolResponse[MCPAudioContent]{
Content: result,
IsError: false,
}
return callToolResp, nil
}
func mcpResourceLinkToolHandle(c *core.WebContext, handler MCPToolHandler[MCPResourceLink], currentConfig *settings.Config, services MCPAvailableServices, callToolReq *MCPCallToolRequest) (any, *errs.Error) {
result, err := handler.Handle(c, callToolReq, currentConfig, services)
if err != nil {
return nil, errs.Or(err, errs.ErrOperationFailed)
}
callToolResp := MCPCallToolResponse[MCPResourceLink]{
Content: result,
IsError: false,
}
return callToolResp, nil
}
func mcpEmbeddedResourceToolHandle(c *core.WebContext, handler MCPToolHandler[MCPEmbeddedResource], currentConfig *settings.Config, services MCPAvailableServices, callToolReq *MCPCallToolRequest) (any, *errs.Error) {
result, err := handler.Handle(c, callToolReq, currentConfig, services)
if err != nil {
return nil, errs.Or(err, errs.ErrOperationFailed)
}
callToolResp := MCPCallToolResponse[MCPEmbeddedResource]{
Content: result,
IsError: false,
}
return callToolResp, nil
}
func getMCPToolInfo[T MCPTextContent | MCPImageContent | MCPAudioContent | MCPResourceLink | MCPEmbeddedResource](name string, handler MCPToolHandler[T]) *MCPTool {
mcpTool := &MCPTool{
Name: name,
Description: handler.Description(),
}
schemeGenerator := jsonschema.Reflector{
Anonymous: true,
DoNotReference: true,
ExpandedStruct: true,
}
if handler.InputType() != nil {
schema := schemeGenerator.ReflectFromType(handler.InputType())
mcpTool.InputSchema = schema
}
if handler.OutputType() != nil {
schema := schemeGenerator.ReflectFromType(handler.OutputType())
mcpTool.OutputSchema = schema
}
return mcpTool
}
+218
View File
@@ -0,0 +1,218 @@
package mcp
import (
"encoding/base64"
"encoding/json"
"github.com/invopop/jsonschema"
)
// MCPProtocolVersion defines the type for Model Context Protocol (MCP) version
type MCPProtocolVersion string
// MCP Protocol Versions
const (
MCPProtocolVersion20250618 MCPProtocolVersion = "2025-06-18"
MCPProtocolVersion20250326 MCPProtocolVersion = "2025-03-26"
MCPProtocolVersion20241105 MCPProtocolVersion = "2024-11-05"
)
// LatestSupportedMCPVersion defines the latest supported version of Model Context Protocol (MCP)
const LatestSupportedMCPVersion = MCPProtocolVersion20250618
// SupportedMCPVersion defines a map of supported MCP versions
var SupportedMCPVersion = map[MCPProtocolVersion]bool{
MCPProtocolVersion20250618: true,
MCPProtocolVersion20250326: true,
MCPProtocolVersion20241105: true,
}
// MCPInitializeRequest defines the request structure for initializing the MCP connection
type MCPInitializeRequest struct {
ProtocolVersion string `json:"protocolVersion"`
ClientInfo *MCPImplementation `json:"clientInfo"`
}
// MCPInitializeResponse defines the response structure for the MCP initialization request
type MCPInitializeResponse struct {
ProtocolVersion string `json:"protocolVersion"`
Capabilities *MCPCapabilities `json:"capabilities"`
ServerInfo *MCPImplementation `json:"serverInfo"`
}
// MCPCapabilities defines the capabilities of the MCP server
type MCPCapabilities struct {
Resources *MCPResourceCapabilities `json:"resources,omitempty"`
Tools *MCPToolCapabilities `json:"tools,omitempty"`
Prompts *MCPPromptCapabilities `json:"prompts,omitempty"`
}
// MCPImplementation defines the client/server information structure sent in the MCP initialization request/response
type MCPImplementation struct {
Name string `json:"name"`
Title string `json:"title,omitempty"`
Version string `json:"version"`
}
// MCPResourceCapabilities defines the capabilities related to resources in the MCP
type MCPResourceCapabilities struct {
Subscribe bool `json:"subscribe"`
ListChanged bool `json:"listChanged"`
}
// MCPToolCapabilities defines the capabilities related to tools in the MCP
type MCPToolCapabilities struct {
ListChanged bool `json:"listChanged"`
}
// MCPPromptCapabilities defines the capabilities related to prompts in the MCP
type MCPPromptCapabilities struct {
ListChanged bool `json:"listChanged"`
}
// MCPListResourcesResponse defines the response structure for listing resources in the MCP
type MCPListResourcesResponse struct {
Resources []*MCPResource `json:"resources"`
NextCursor string `json:"nextCursor,omitempty"`
}
// MCPResource defines the structure of a resource in the MCP
type MCPResource struct {
URI string `json:"uri"`
Name string `json:"name"`
Size int `json:"size,omitempty"`
MimeType string `json:"mimeType,omitempty"`
Title string `json:"title,omitempty"`
Description string `json:"description,omitempty"`
}
// MCPReadResourceRequest defines the request structure for reading a resource in the MCP
type MCPReadResourceRequest struct {
URI string `json:"uri"`
}
// MCPReadResourceResponse defines the response structure for reading a resource in the MCP
type MCPReadResourceResponse[T MCPTextResourceContents | MCPBlobResourceContents] struct {
Contents []*T `json:"contents"`
}
// MCPTextResourceContents defines the text contents structure of a resource in the MCP
type MCPTextResourceContents struct {
URI string `json:"uri"`
Text string `json:"text"`
MimeType string `json:"mimeType,omitempty"`
}
// MCPBlobResourceContents defines the blob contents structure of a resource in the MCP
type MCPBlobResourceContents struct {
URI string `json:"uri"`
Blob string `json:"blob"` // Base64 encoded content of the resource
MimeType string `json:"mimeType,omitempty"`
}
// MCPListToolsResponse defines the response structure for listing tools in the MCP
type MCPListToolsResponse struct {
Tools []*MCPTool `json:"tools"`
NextCursor string `json:"nextCursor,omitempty"`
}
// MCPTool defines the structure of a tool in the MCP
type MCPTool struct {
Name string `json:"name"`
InputSchema *jsonschema.Schema `json:"inputSchema"`
OutputSchema *jsonschema.Schema `json:"outputSchema"`
Title string `json:"title,omitempty"`
Description string `json:"description,omitempty"`
}
// MCPCallToolRequest defines the request structure for listing tools in the MCP
type MCPCallToolRequest struct {
Name string `json:"name"`
Arguments json.RawMessage `json:"arguments,omitempty"`
}
// MCPCallToolResponse defines the response structure for calling a tool in the MCP
type MCPCallToolResponse[T MCPTextContent | MCPImageContent | MCPAudioContent | MCPResourceLink | MCPEmbeddedResource] struct {
Content []*T `json:"content"`
IsError bool `json:"isError,omitempty"`
}
// MCPTextContent defines the text content structure used in MCP
type MCPTextContent struct {
Type string `json:"type"`
Text string `json:"text"`
}
// MCPImageContent defines the image content structure used in MCP
type MCPImageContent struct {
Type string `json:"type"`
MimeType string `json:"mimeType"`
Data string `json:"data"` // Base64 encoded content for binary data
}
// MCPAudioContent defines the audio content structure used in MCP
type MCPAudioContent struct {
Type string `json:"type"`
MimeType string `json:"mimeType"`
Data string `json:"data"` // Base64 encoded content for binary data
}
// MCPResourceLink defines the resource link content structure used in MCP
type MCPResourceLink struct {
URI string `json:"uri"`
Type string `json:"type"`
Name string `json:"name"`
Size int `json:"size,omitempty"`
MimeType string `json:"mimeType,omitempty"`
Title string `json:"title,omitempty"`
Description string `json:"description,omitempty"`
}
// MCPEmbeddedResource defines the embedded resource content structure used in MCP
type MCPEmbeddedResource struct {
Type string `json:"type"`
Resource any `json:"resource"`
}
// NewMCPTextContent creates a new instance of MCPTextContent with the given text
func NewMCPTextContent(text string) *MCPTextContent {
return &MCPTextContent{
Type: "text",
Text: text,
}
}
// NewMCPImageContent creates a new instance of MCPImageContent with the given data and MIME type
func NewMCPImageContent(data []byte, mimeType string) *MCPImageContent {
return &MCPImageContent{
Type: "image",
MimeType: mimeType,
Data: base64.StdEncoding.EncodeToString(data),
}
}
// NewMCPAudioContent creates a new instance of MCPAudioContent with the given data and MIME type
func NewMCPAudioContent(data []byte, mimeType string) *MCPAudioContent {
return &MCPAudioContent{
Type: "audio",
MimeType: mimeType,
Data: base64.StdEncoding.EncodeToString(data),
}
}
// NewMCPResourceLink creates a new instance of MCPResourceLink with the given parameters
func NewMCPResourceLink(uri string, name string) *MCPResourceLink {
return &MCPResourceLink{
URI: uri,
Type: "resource_link",
Name: name,
}
}
// NewMCPEmbeddedResource creates a new instance of MCPEmbeddedResource with the given resource
func NewMCPEmbeddedResource[T MCPTextResourceContents | MCPBlobResourceContents](resource *T) *MCPEmbeddedResource {
return &MCPEmbeddedResource{
Type: "resource",
Resource: resource,
}
}