HackMD

Exposes HackMD API operations as a standardized set of 12 tools through the Model Context Protocol, implementing the MCP server specification with tool schema validation and request/response marshaling. The server implements the MCP tool interface by wrapping HackMD REST API calls into discrete, discoverable tools that AI assistants can invoke via standard MCP protocol messages, handling authentication token injection and response transformation automatically.

Implements both STDIO and HTTP transport mechanisms for the MCP protocol, with transport mode selected at startup via the TRANSPORT environment variable evaluated in index.ts. The server instantiates either a StdioServerTransport (for local desktop clients like Claude Desktop) or HttpServerTransport (for remote/cloud deployments) based on configuration, allowing a single codebase to support both local and distributed deployment scenarios without code branching.

Defines tool schemas in server.json that specify tool names, descriptions, input parameters, and validation rules for all 12 exposed tools. The MCP server uses these schemas to validate incoming tool call requests before invoking HackMD API operations, ensuring parameters match expected types and constraints. The schema-driven approach enables MCP clients to discover tool capabilities and parameter requirements through standard MCP introspection without hardcoding tool knowledge.

Provides the get_user_info tool that retrieves authenticated user profile information from HackMD by calling the HackMD API with the provided API token. The tool returns user metadata including user ID, username, email, and account settings, enabling AI assistants to establish context about the authenticated user and personalize operations based on user identity and account configuration.

Implements the list_teams tool that retrieves all teams accessible to the authenticated user from HackMD's API, returning team metadata including team IDs, names, and member information. The tool enables AI assistants to discover collaborative team contexts and determine which teams the user has access to, supporting team-scoped operations like reading and creating team notes.

Exposes the get_history tool that retrieves the authenticated user's HackMD reading history, returning a chronologically-ordered list of recently accessed notes with timestamps and metadata. The tool enables AI assistants to understand user context by examining recent note activity, supporting workflows that need to reference recently-viewed documents or reconstruct user work context.

Implements four tools (list_user_notes, get_note, create_note, update_note, delete_note) providing complete CRUD operations on user-owned notes stored in HackMD. Each tool maps to HackMD REST API endpoints, handling request validation, authentication token injection, and response transformation. The tools enable AI assistants to read note content, create new notes, modify existing notes, and delete notes, supporting full note lifecycle management within AI-assisted workflows.

Implements four tools (list_team_notes, create_team_note, update_team_note, delete_team_note) providing CRUD operations on notes owned by teams rather than individual users. These tools require a team ID parameter and operate within team authorization boundaries, enabling AI assistants to manage collaborative team documents. The tools handle team context validation and ensure operations respect team-level permissions and access controls.

Manages HackMD API authentication by reading the HACKMD_API_TOKEN environment variable and injecting the token into all outbound API requests as a Bearer token in the Authorization header. The implementation handles token validation at server startup and provides consistent authentication across all 12 tools without requiring per-tool token management. The server acts as a stateless authentication proxy, forwarding authenticated requests to HackMD's REST API.

Implements MCP protocol message handling by serializing tool requests from MCP clients into HackMD API calls and marshaling HackMD API responses back into MCP-compliant JSON responses. The server handles parameter validation against tool schemas, error transformation, and response formatting to ensure all tool outputs conform to MCP protocol specifications. This enables transparent communication between MCP clients and HackMD API without clients needing to understand HackMD's native API format.

Distributes hackmd-mcp through three distinct channels (NPM registry, OCI container registry, and MCPB GitHub releases) with version management and automated publishing. Each distribution channel is optimized for different deployment scenarios: NPM for local development via npx, OCI for containerized deployments, and MCPB for MCP-aware platforms. The server.json configuration file specifies all distribution channels, enabling single-source version management across multiple deployment targets.