convez.ai
MCP ServerIntegração & APIsIntermediário
Smeldr

Smeldr MCP Server

Smeldr/mcp

Conect seu CMS Smeldr a Claude com tipos automáticos e segurança integrada

Ver no GitHub
InicialPluginScore · de 0 a 100

Servidor MCP que expõe módulos de conteúdo tipados do Smeldr como recursos e ferramentas para Claude, Cursor e assistentes compatíveis. Permite que agentes de IA criem, leiam, atualizem e deletem conteúdo com validação de schema e controle de acesso automáticos, sem bypasses.

Instalação

$npx convez-ai Smeldr/mcp

1 comando no terminal: detecta o formato do repositório (marketplace ou plugin avulso) e instala via Claude Code. Requer Node 18+ e o Claude Code instalado.

Métricas

Estrelas
1
Forks
0
Acompanhando
1
Saúde
50%
Último commit
há 2 dias
Versão
v1.77.3
Issues abertas
0
Contribuidores
1

Casos de uso

  • Conectar módulos de conteúdo Smeldr ao Claude Desktop e Cursor
  • Expor APIs de CRUD tipadas para agentes IA acessarem dados com validação
  • Integração remota autenticada via SSE para acesso centralizado

Veredito

MCP server robusto e bem arquitetado que bridgeia o Smeldr (CMS/framework de conteúdo em Go) com o ecossistema Claude. Ideal para quem já usa Smeldr e quer expor dados tipados a assistentes IA mantendo segurança e validação automáticas.

README

A tradução para o português deste README ainda está na fila.

smeldr.dev/mcp

✅ Available — MCP (Model Context Protocol) server for Smeldr apps.

smeldr.dev/mcp wraps a smeldr.App and exposes its MCP-registered content modules as MCP resources and tools, enabling Claude Desktop, Cursor, and any MCP-compatible AI assistant to create, read, update, publish, and delete content through the Model Context Protocol.

Schema derivation, role enforcement, and lifecycle rules are automatic — they use the same code paths as the HTTP layer. There is no special MCP bypass.


Quick start

go get smeldr.dev/mcp
package main

import (
	"context"
	"os"

	"smeldr.dev/mcp"

	"smeldr.dev/core"
)

// BlogPost is your content type — embed smeldr.Node and add your fields.
type BlogPost struct {
	smeldr.Node
	Title string `smeldr:"required" json:"title"`
	Body  string `smeldr:"required,min=50" json:"body"`
}

func main() {
	app := smeldr.New(smeldr.Config{
		BaseURL: "https://mysite.com",
		Secret:  []byte(os.Getenv("SECRET")),
	})

	posts := smeldr.NewModule((*BlogPost)(nil),
		smeldr.At("/posts"),
		smeldr.Repo(smeldr.NewMemoryRepo[*BlogPost]()),
		smeldr.MCP(smeldr.MCPWrite), // expose as MCP tools
	)
	app.Content(posts)

	srv := mcp.New(app)
	if err := srv.ServeStdio(context.Background(), os.Stdin, os.Stdout); err != nil {
		os.Exit(1)
	}
}

Build the binary:

go build -o myapp-mcp .

Migrating from v1.16.x

The package was renamed forgemcp → mcp in v1.17.0. Replace forgemcp.X with mcp.X at all call sites (or drop the import alias: import "smeldr.dev/mcp"). No exported symbols changed — only the package qualifier. The smeldr.dev/oauth dependency moved to v0.2.0 (forgeoauth → oauth); if you wire OAuth via WithOAuth, update that import too.


Claude Desktop

Add to ~/Library/Application Support/Claude/claude_desktop_config.json (macOS) or %APPDATA%\Claude\claude_desktop_config.json (Windows):

{
  "mcpServers": {
    "myapp": {
      "command": "/absolute/path/to/myapp-mcp",
      "env": {
        "SECRET": "your-hmac-secret"
      }
    }
  }
}

Replace /absolute/path/to/myapp-mcp with the path to the compiled binary. Restart Claude Desktop to pick up the new server.


Cursor

Add to .cursor/mcp.json in your project root (or ~/.cursor/mcp.json globally):

{
  "mcpServers": {
    "myapp": {
      "command": "/absolute/path/to/myapp-mcp",
      "env": {
        "SECRET": "your-hmac-secret"
      }
    }
  }
}

SSE (remote / authenticated)

For remote access over HTTP, use the SSE transport:

// In your main app or a dedicated MCP server binary:
mux := http.NewServeMux()
mux.Handle("/", mcp.New(app).Handler())
http.ListenAndServe(":9090", mux)

The SSE handler registers two routes:

  • GET /mcp — establishes the event stream; the client keeps this connection open.
  • POST /mcp/message — accepts JSON-RPC requests. Requires Authorization: Bearer <token>.

Getting a token

Use smeldr.SignToken to mint a token with the same HMAC secret as your app:

token, err := smeldr.SignToken(smeldr.User{
	ID:    "alice",
	Roles: []smeldr.Role{smeldr.Author},
}, []byte(os.Getenv("SECRET")), 0) // 0 = no expiry

MCP client configuration (SSE)

{
  "mcpServers": {
    "myapp-remote": {
      "url": "https://mysite.com/mcp",
      "headers": {
        "Authorization": "Bearer eyJ..."
      }
    }
  }
}

MCPRead vs MCPWrite

Register each module with the operations you want:

smeldr.MCP(smeldr.MCPRead)                    // read-only access
smeldr.MCP(smeldr.MCPWrite)                   // write-only access
smeldr.MCP(smeldr.MCPRead, smeldr.MCPWrite)    // full access
MCP methodRequiresRole requiredWhat it does
resources/listMCPReadanyList all Published items across all MCPRead modules
resources/templates/listMCPReadanyReturn the URI template for each MCPRead module
resources/read {uri}MCPReadanyFetch a single Published item by URI
tools/call create_{type}MCPWriteAuthor+Create a Draft item; returns the saved item as JSON
tools/call update_{type}MCPWriteAuthor+Partially update fields by slug; non-supplied fields retained
tools/call publish_{type}MCPWriteAuthor+Transition Draft → Published; idempotent
tools/call schedule_{type}MCPWriteAuthor+Set Scheduled status and scheduled_at (RFC 3339)
tools/call archive_{type}MCPWriteAuthor+Set Archived status
tools/call delete_{type}MCPWriteAuthor+Permanently delete an item
tools/call list_{type}sMCPWriteEditor+List all items at any status; optional status filter
tools/call get_{type}MCPWriteEditor+Get a single item by slug at any status

Tool naming: type names are converted to lower_snake_case, with consecutive uppercase letters treated as one word. BlogPost → blog_post, MCPDocument → mcp_document. Full examples: create_blog_post, update_blog_post, publish_blog_post.

Resource URI format: smeldr://{prefix}/{slug} — for example, smeldr://posts/hello-world for a post at /posts/hello-world. Legacy forge:// URIs are still accepted on resources/read and resources/subscribe during the deprecation window (T87 removes legacy accept).

Field names in create_* and update_* arguments: use the JSON field name (lowercase, respecting any json: tag). For Title string with no json tag, the argument key is "title". For Tags string \json:"tags"`, the key is "tags"`.


Admin read tools

Each MCPWrite module also exposes two admin read tools that require Editor or Admin role. Unlike resources/read, these tools return content at any lifecycle status — Draft, Scheduled, Published, or Archived.

ToolArgumentsReturns
list_{type}sstatus?: "draft"|"scheduled"|"published"|"archived"[]T — all items, or filtered by status
get_{type}slug: stringT — single item
// Example: list all posts regardless of status
// Tool name: list_blog_posts (type BlogPost → snake blog_post + s)

// Example: get a single post by slug
// Tool name: get_blog_post

Tool naming: follows the same snake_case rule as write tools. BlogPost → blog_post, so the list tool is list_blog_posts and the get tool is get_blog_post.

Return value: the full struct including all smeldr.Node fields (Status, PublishedAt, ScheduledAt, CreatedAt, UpdatedAt, Slug, ID).


Block system tools (WithBlocks)

Enable the block-system tools with the WithBlocks option. They let an AI operator create generic blocks and compose them into pages and collections. The tools read and write the smeldr_dynamic_content and smeldr_content_edges tables — create them once at startup with smeldr.CreateBlockTables(db).

smeldr.CreateBlockTables(db)
mcpSrv := mcp.New(app, mcp.WithBlocks())

Blocks are addressed by ID (they have no slug) and are not exposed as resources/* — read them with get_node / list_nodes.

ToolRoleArguments
create_nodeAuthor+type_name, fields (object) → {id, type_name, status, slug}
update_nodeAuthor+id, fields (merged onto stored; type_name immutable)
get_nodeAuthor+id
list_nodesAuthor+type_name?, status?
publish_node / archive_nodeAuthor+id (publish idempotent)
add_section / add_itemEditor+parent_id, child_id (types derived)
reorder_sections / reorder_itemsEditor+parent_id, ordered_child_ids
remove_section / remove_itemEditor+parent_id, child_id

Sections (edge_role "section") compose pages; items ("item") compose collections. The names are distinct for clarity; both share one implementation.


Lifecycle enforcement

MCPRead exposes only Published items. Draft, Scheduled, and Archived items are invisible to resources/list and return MCP error -32001 on resources/read. This enforcement is unconditional — it applies regardless of the caller's role and cannot be disabled.

MCPWrite tools operate on items at any lifecycle stage. The full transition table:

Draft      → Published  (publish_{type})
Draft      → Scheduled  (schedule_{type}, requires scheduled_at RFC 3339)
*, *       → Archived   (archive_{type})
Published  → Published  (publish_{type} is idempotent — no error, no duplicate signal)

The Smeldr scheduler automatically transitions Scheduled → Published at the configured time without any MCP call.


Role enforcement

stdio transport (ServeStdio)

ServeStdio runs with smeldr.Admin privileges. It is designed for local, trusted processes only — any process that can write to stdin has full content access. Do not expose the MCP binary's stdin to untrusted processes.

SSE transport (Handler)

POST /mcp/message enforces authentication on every request:

  • No Authorization: Bearer <token> header → HTTP 401
  • Valid token, but role < smeldr.Author → MCP error -32001 (not HTTP 401; authentication succeeded, authorisation failed)
  • All tools/call operations require smeldr.Author role or above

Tokens are minted and verified using the same HMAC mechanism as the Smeldr REST API (smeldr.BearerHMAC). A token from smeldr.SignToken(user, secret, 0) is valid for both the REST API and the SSE MCP transport — there is no separate token format.


Zero dependencies

smeldr.dev/mcp has zero external dependencies. All MCP transport and JSON-RPC 2.0 protocol handling is implemented using the Go standard library only.


Secret rotation (WithSecret)

mcp.New(app) automatically inherits the HMAC secret from app.Config.Secret. You only need WithSecret during a secret rotation window — when you need to accept tokens signed with a different secret than the one currently in Config.Secret:

srv := mcp.New(app, mcp.WithSecret(oldSecret))

If the provided secret differs from app.Config.Secret, a warning is logged at startup. Remove WithSecret once rotation is complete.

Ver o original no GitHub

Bom para

Relacionados