convez.ai
MCP ServerIntegração & APIsIntermediário
asgard-ai-platform

MCP Heimdall

asgard-ai-platform/mcp-heimdall

Acesso seguro e estruturado ao CMS Asgard via MCP

Ver no GitHub
InicialPluginScore · de 0 a 100

Servidor MCP que expõe ferramentas somente leitura para a plataforma de gerenciamento de conteúdo Asgard. Fornece 26 ferramentas para acessar recursos como artigos, avatares, contas, aplicativos, missões, publicações e tópicos através de autenticação por token bearer.

Instalação

$npx convez-ai asgard-ai-platform/mcp-heimdall

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
0
Forks
0
Acompanhando
0
Saúde
62%
Último commit
há 2 meses
Versão
—
Issues abertas
1
Contribuidores
4

Casos de uso

  • Integrar Claude com plataforma de conteúdo Asgard
  • Consultar dados de artigos, missões e publicações programaticamente
  • Automatizar fluxos que envolvem leitura de conteúdo gerenciado

Veredito

MCP server bem estruturado e documentado para integração com Asgard CMS. Abordagem read-only apropriada para segurança, embora escopo seja bastante específico ao ecossistema Asgard.

README

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

MCP Heimdall

CI PyPI version Python versions GitHub tag GitHub stars GitHub issues GitHub last commit License: MIT MCP

Heimdall — an MCP (Model Context Protocol) server that exposes read-only tools for Asgard's content management platform.

Provides list and get tools for all major resources: articles, blobs, content sources, article templates, avatars, accounts, apps, missions, mission contents, publications, topics, and workspaces.

繁體中文

Part of the Asgard AI Platform open-source ecosystem.


What This Does

  • 26 MCP tools covering workspace, article, avatar, account, app, blob, content source, mission, publication, and topic resources
  • Read-only tool surface for safe AI assistant access
  • Bearer token authentication through HEIMDALL_API_TOKEN
  • Public-safe configuration through environment variables and .env.example
  • stdio transport for local MCP clients

See docs/tools.md for the full public tool reference.


Quick Start

Install

pip install mcp-heimdall

Run with uvx without installing globally:

uvx --from mcp-heimdall mcp-heimdall

For local development:

git clone https://github.com/asgard-ai-platform/mcp-heimdall.git
cd mcp-heimdall
uv sync

Set your API token:

export HEIMDALL_API_TOKEN=your_bearer_token_here

For local development, copy .env.example to .env and set HEIMDALL_API_TOKEN. HEIMDALL_API_BASE_URL is optional unless you need an override.

See docs/configuration.md for details.

Use with Claude Code

After installing the package and configuring environment variables, add the stdio MCP server:

claude mcp add --transport stdio heimdall -- mcp-heimdall

For a local checkout:

claude mcp add --transport stdio heimdall -- uv --directory /path/to/mcp-heimdall run mcp-heimdall

Use with Claude Desktop

Package install / uvx example:

{
  "mcpServers": {
    "heimdall": {
      "command": "uvx",
      "args": ["mcp-heimdall"],
      "env": {
        "HEIMDALL_API_TOKEN": "your_bearer_token_here"
      }
    }
  }
}

For a local checkout, run it through uv from the repository directory:

{
  "mcpServers": {
    "heimdall": {
      "command": "uv",
      "args": ["run", "--directory", "/path/to/mcp-heimdall", "mcp-heimdall"],
      "env": {
        "HEIMDALL_API_TOKEN": "your_bearer_token_here"
      }
    }
  }
}

More examples are available in examples/.


Test

# Public import smoke test
uv run python tests/test_imports.py

# Unit tests (mocked HTTP, no live API needed)
uv run python -m pytest tests/test_all_tools.py -v

# Compile source and tests
uv run python -m compileall src tests

# Build source distribution and wheel
uv build

Configuration

Environment VariableRequiredDefaultDescription
HEIMDALL_API_TOKENYes—Bearer token for the API
HEIMDALL_API_BASE_URLNohttps://heimdall-api.asgard-ai.comAPI base URL override

Tools (26)

All workspace-scoped tools require a workspace_id parameter.
Use list_workspaces first to discover available workspace IDs.

Workspace

ToolDescriptionParameters
list_workspacesList all workspaces for the current user—
get_workspaceGet a workspace by IDworkspace_id

Article

ToolDescriptionParameters
list_articlesList articles in a workspaceworkspace_id, page, size
get_articleGet an article by IDworkspace_id, article_id

Article Template

ToolDescriptionParameters
list_article_templatesList article templates in a workspaceworkspace_id, page, size
get_article_templateGet an article template by IDworkspace_id, article_template_id

Avatar

ToolDescriptionParameters
list_avatarsList avatars in a workspaceworkspace_id, page, size, name*, gender*
get_avatarGet an avatar by IDworkspace_id, avatar_id

Account (Platform Account)

ToolDescriptionParameters
list_accountsList platform accounts in a workspaceworkspace_id, page, size, provider_type*, app_id*
get_accountGet a platform account by IDworkspace_id, account_id
get_accounts_by_avatarGet all accounts linked to an avatarworkspace_id, avatar_id

App (OAuth App)

ToolDescriptionParameters
list_appsList OAuth apps in a workspaceworkspace_id, page, size, provider_type*
get_appGet an OAuth app by IDworkspace_id, app_id

Blob

ToolDescriptionParameters
list_blobsList blob records in a workspaceworkspace_id, page, size, filter_by*, filter_value*

Content Source

ToolDescriptionParameters
list_content_sourcesList content sources in a workspaceworkspace_id, page, size
get_content_sourceGet a content source by IDworkspace_id, content_source_id

Mission

ToolDescriptionParameters
list_missionsList missions in a workspaceworkspace_id, page, size, topic_id*, avatar_id*, mission_type*, q*, sort_by*, sort_order*
get_missionGet a mission by IDworkspace_id, mission_id
export_missionExport a mission with all its contentsworkspace_id, mission_id

Mission Content

ToolDescriptionParameters
list_mission_contentsList mission contents in a workspaceworkspace_id, page, size, mission_id*, avatar_id*, status*
get_mission_contentGet a mission content by IDworkspace_id, mission_content_id

Publication

ToolDescriptionParameters
list_publicationsList publications in a workspaceworkspace_id, page, size
get_publicationGet a publication by IDworkspace_id, publication_id

Topic

ToolDescriptionParameters
list_topicsList topics in a workspaceworkspace_id, page, size, name*
get_topicGet a topic by IDworkspace_id, topic_id
list_topic_categoriesList all available topic categoriesworkspace_id

* optional filter parameter


MCP Client Configuration

Add this to your MCP client config (e.g. Claude Desktop claude_desktop_config.json) when running from a local checkout:

{
  "mcpServers": {
    "heimdall": {
      "command": "uv",
      "args": ["run", "--directory", "/path/to/mcp-heimdall", "mcp-heimdall"],
      "env": {
        "HEIMDALL_API_TOKEN": "your_bearer_token_here"
      }
    }
  }
}

Or with a .env file:

{
  "mcpServers": {
    "heimdall": {
      "command": "uv",
      "args": [
        "run",
        "--env-file", "/path/to/mcp-heimdall/.env",
        "--directory", "/path/to/mcp-heimdall",
        "mcp-heimdall"
      ]
    }
  }
}

Documentation


Boundaries

  • The server exposes read-only MCP tools only.
  • The server operates with the permissions of the configured HEIMDALL_API_TOKEN.
  • Heimdall write APIs are intentionally not exposed through this MCP server.
  • Public documentation intentionally avoids linking to private backend API documents.

Architecture

stdio (JSON-RPC 2.0)
  → mcp-heimdall (console script entry point)
    → src/mcp_heimdall/server.py       — entry point, imports trigger tool registration
      → src/mcp_heimdall/app.py        — MCPServer singleton (FastMCP "mcp-heimdall")
        → src/mcp_heimdall/tools/*     — @mcp.tool() decorated functions
          → src/mcp_heimdall/connectors/rest_client.py  — HTTP client with retry + extra_headers support
            → src/mcp_heimdall/auth/bearer.py           — reads HEIMDALL_API_TOKEN env var
              → src/mcp_heimdall/config/settings.py     — base URL + endpoint map

License

MIT

Ver o original no GitHub

Bom para

Relacionados