# Minh Spark developer resources

Minh Spark publishes web, AI, mobile and data projects, technical articles and open-source tools. This guide identifies the public integration surface of minhspark.com and the documentation for individual projects.

## When to use this site

Use the website to identify Minh Spark's official projects, find developer documentation, review the public portfolio, or locate contact and policy information. Start from the [OpenAPI document](https://minhspark.com/openapi.json) for the machine-readable API surface, or use the website MCP tools for a small, structured directory of those public resources. For coding-agent communication on a local machine, use the separate Codex MCP Bridge project and its own setup guide.

## OpenAPI document

[`https://minhspark.com/openapi.json`](https://minhspark.com/openapi.json) is an OpenAPI 3.1 description of every public endpoint. Each operation carries a unique `operationId`, a description, typed parameters and a response schema, so it converts directly into LLM function-calling definitions.

```sh
curl -sS https://minhspark.com/openapi.json | jq '.paths | keys'
```

The document covers the discovery files (`/openapi.json`, `/llms.txt`, `/sitemap.xml`), the Markdown representations of public pages, `/api/health`, `/api/guestbook`, `/api/views` and `/api/mcp`. Write endpoints exist on this host but are excluded on purpose: checkout, orders, payments, subscriptions, guestbook submissions and contact messages create side effects for a person, so send a human to the matching page instead of calling them.

### Error responses

Every API route answers a failure with JSON, never an HTML error page. The body matches the `ApiError` schema:

```json
{
  "error": "Method POST Not Allowed",
  "code": "method_not_allowed",
  "message": "Method POST Not Allowed",
  "hint": "Retry with GET.",
  "docs": "https://minhspark.com/developers/"
}
```

Branch on `code`, which is stable: `method_not_allowed`, `not_found`, `not_configured`, `invalid_request`, `rate_limited`, `upstream_error`, `internal_error`. The wording of `message` may change. `hint` names the next step that resolves the error, and a path no endpoint serves returns `not_found` in JSON rather than the site's HTML 404 page.

## Command line tool

`@minhspark/cli` reads the same public surface from a shell. It has no runtime dependencies, needs Node.js 20 or newer, and every command is read-only.

```sh
npx @minhspark/cli operations            # every documented operation: id, method, path
npx @minhspark/cli openapi --path /api/health
npx @minhspark/cli health                # exits 1 when a dependency is down
npx @minhspark/cli page about            # any public page as Markdown
npx @minhspark/cli info                  # site overview through the MCP tool
```

Failures print the server's `code` and `hint`, so the message says what to do next. `--site <url>` targets another deployment, which is useful against a preview URL.

## Website MCP connection

- Endpoint: `https://minhspark.com/api/mcp`
- Transport: MCP Streamable HTTP, using JSON responses.
- Authentication: none; every tool returns public, read-only information.
- Session model: stateless; no `MCP-Session-Id` is required.
- Tools: `get_site_info` returns the site overview; `list_developer_resources` returns official public documentation links. Both accept an empty arguments object.
- Boundaries: the endpoint cannot access local development sessions, customer accounts, orders, payments, private files or secrets. It has no write tools.

Connect with a client that supports [MCP Streamable HTTP](https://modelcontextprotocol.io/specification/2025-11-25/basic/transports). Each JSON-RPC message is a separate POST. Send `Content-Type: application/json` and `Accept: application/json, text/event-stream`.

Initialize the connection:

```sh
curl -sS https://minhspark.com/api/mcp \
  -H 'Content-Type: application/json' \
  -H 'Accept: application/json, text/event-stream' \
  --data '{"jsonrpc":"2.0","id":1,"method":"initialize","params":{"protocolVersion":"2025-11-25","capabilities":{},"clientInfo":{"name":"minhspark-docs-example","version":"1.0.0"}}}'
```

Read `result.protocolVersion` from the response. Use that negotiated version in the `MCP-Protocol-Version` header on subsequent requests. The following examples assume the negotiated version is `2025-11-25`.

Send the initialized notification; a successful notification returns HTTP 202 with an empty body:

```sh
curl -sS -i https://minhspark.com/api/mcp \
  -H 'Content-Type: application/json' \
  -H 'Accept: application/json, text/event-stream' \
  -H 'MCP-Protocol-Version: 2025-11-25' \
  --data '{"jsonrpc":"2.0","method":"notifications/initialized"}'
```

List the available tools:

```sh
curl -sS https://minhspark.com/api/mcp \
  -H 'Content-Type: application/json' \
  -H 'Accept: application/json, text/event-stream' \
  -H 'MCP-Protocol-Version: 2025-11-25' \
  --data '{"jsonrpc":"2.0","id":2,"method":"tools/list","params":{}}'
```

Read the developer resource directory:

```sh
curl -sS https://minhspark.com/api/mcp \
  -H 'Content-Type: application/json' \
  -H 'Accept: application/json, text/event-stream' \
  -H 'MCP-Protocol-Version: 2025-11-25' \
  --data '{"jsonrpc":"2.0","id":3,"method":"tools/call","params":{"name":"list_developer_resources","arguments":{}}}'
```

The service does not offer a standalone SSE subscription, so GET returns HTTP 405. Requests with an unsupported protocol version or invalid JSON-RPC input fail instead of executing a tool. An absent Origin header is accepted for server-side clients; a supplied Origin must be the canonical site origin or its www origin. This is not a general cross-origin browser API. Never include passwords, tokens or personal customer information in a request.

## Project documentation

- [Codex MCP Bridge](https://github.com/buidangminh23/codex-mcp-bridge#readme): connect Codex and Claude workflows in your own development environment. The npm package is `@minhspark/codex-mcp-bridge`; use its README for installation, supported clients and authorization. This is separate from the public website MCP endpoint.
- [Spacing Skill](https://github.com/buidangminh23/spacing-skill#readme): interface spacing and layout guidance for coding agents.
- [Icons Pro Max](https://github.com/buidangminh23/icons-pro-max#readme): icon selection and integration guidance for product interfaces.
- [Public source repositories](https://github.com/buidangminh23): authoritative repository documentation and project-specific issue trackers.

## Machine-readable website content

Start with [llms.txt](https://minhspark.com/llms.txt) for task-specific guidance, [openapi.json](https://minhspark.com/openapi.json) for the API surface and [sitemap.xml](https://minhspark.com/sitemap.xml) for public URLs. Request the homepage with `Accept: text/markdown` for its Markdown representation, or `Accept: text/html` for the browser page. Appending `.md` to a page path returns the same Markdown. Check the response Content-Type and HTTP status before consuming the body.

## Contact and policies

Read [About Minh Spark](https://minhspark.com/about/), [Contact](https://minhspark.com/contact/), [Privacy](https://minhspark.com/privacy/) and [Rules and policies](https://minhspark.com/chinh-sach/) before making service decisions. The website MCP tools only retrieve public information; purchases and support requests remain in their existing website flows.