Content
# xmlui-mcp: Model Context Protocol server for XMLUI
This project provides both a standalone CLI tool and a Go library for integrating XMLUI MCP capabilities into other applications.
This kit provides an MCP server that you can use with an MCP-aware tool, like Claude Desktop or Cursor, to empower those agents to help you build [XMLUI](https://xmlui.org) apps.
## Features
- **Standalone CLI**: Run as a command-line tool for MCP clients
- **Go Library**: Import into other Go applications as a library
- **Multiple Modes**: Support for stdio and HTTP server modes
- **Session Management**: Track and manage multiple user sessions
- **Analytics**: Built-in usage tracking and analytics
- **Extensible**: Easy to extend with custom tools and prompts
- [Prerequisites](#prerequisites)
- [Install](#install)
- [Configure](#configure)
- [Test](#test-the-server)
- [Library Usage](#library-usage)
- [API Reference](#api-reference)
In order to be able to search XMLUI documentation and source code, the server will automatically download the latest XMLUI repository from GitHub. The repository is cached in:
- **Linux**: `$XDG_CACHE_HOME/xmlui/xmlui-mcp` or `~/.cache/xmlui/xmlui-mcp`
- **macOS**: `~/Library/Caches/xmlui/xmlui-mcp`
- **Windows**: `%LOCALAPPDATA%\xmlui\xmlui-mcp`
The download happens once and is reused on subsequent runs. The server will fetch the latest `xmlui@<version>` release from GitHub.
## Install
To install, download the zip for your platform from [https://github.com/xmlui-org/xmlui-mcp/releases](https://github.com/xmlui-org/xmlui-mcp/releases) and unzip into a known locaton like ~/xmlui-mcp. On Mac, run `prepare-binary.sh` to handle permissions.
## Configure
The simplest configuration just names the location of the binary. The server will search the cached repo.
```json
{
"mcpServers": {
"xmlui": {
"command": "/Users/jonudell/xmlui-mcp/xmlui-mcp"
}
}
}
```
If you want to have the server also search one or more XMLUI projects, use the `-e` flag (repeatable):
```json
{
"mcpServers": {
"xmlui": {
"command": "/Users/jonudell/xmlui-mcp/xmlui-mcp",
"args": [
"-e", "/Users/jonudell/xmlui-invoice",
"-e", "/Users/jonudell/xmlui-mastodon"
]
}
}
}
```
```
Usage of xmlui-mcp:
-e value
Example directory path (can be repeated)
-example value
Example directory path (can be repeated, alias for -e)
-http
Run in HTTP mode instead of stdio
-port string
Port to listen on in HTTP mode (default "8080")
-xmlui-version string
Specific XMLUI version to use (e.g. 0.11.4)
```
The paths for these config files on a Mac are:
**Claude:** ~/Library/Application Support/Claude/claude_desktop_config.json
**Cursor:** ~/.cursor.mcp.json
**Copilot:** ~/Library/Application Support/Code/User/mcp.json (created initially by `MCP: Add Server`)
With this setup I am giving the agents access to the XMLUI projects I'm working on (xmlui-invoice, xmlui-mastodon), so they can both read and write those projects.
I am also encouraging them to use the xmlui-mcp tools as we work on those projects. Here's what that looks like.
<img width="737" alt="image" src="https://github.com/user-attachments/assets/1f87519c-1338-4eca-a730-9f2e0c1a64a9" />
<img width="788" alt="image" src="https://github.com/user-attachments/assets/4793a475-46d1-418e-ad6a-0760af53ddca" />
## Tips for working with agents that use this server
As agents use this server to search docs and examples, they receive strong guidance to prefer working examples, cite URLs when found, and admit ignorance when not found.
It helps to reinforce that guidance in their rules files.
- Obey the guidance you receive from the xmlui-mcp server.
- I will disbelieve any answer for which you cannot cite an URL to documentation or a working example.
- If you don't find an URL, say so.
- If you do find one, cite it.
Despite all this guidance, agents can wrongly report solutions for which they did not find documented examples. You can minimize that risk by being explicit in every interaction.
Instead of: _How can I right-align a Column in an XMLUI Table_
Say: _Show me a documented example of right-aligning a Column in an XMLUI Table_
## Library Usage
This project can be used as a Go library in other applications. The CLI is a thin wrapper around the library functionality.
### Basic Usage with Automatic Download
```go
import "xmlui-mcp/pkg/xmluimcp"
func main() {
// XMLUI repository is automatically downloaded and cached by NewServer
config := xmluimcp.ServerConfig{
ExampleRoot: "/path/to/examples",
ExampleDirs: []string{"demo", "tutorial"},
HTTPMode: false, // stdio mode
Port: "8080",
}
server, err := xmluimcp.NewServer(config)
if err != nil {
log.Fatal(err)
}
// Print startup information
server.PrintStartupInfo()
// Start the server
if config.HTTPMode {
err = server.ServeHTTP()
} else {
err = server.ServeStdio()
}
if err != nil {
log.Fatal(err)
}
}
```
### Integration Example
```go
// In your go.mod:
// require xmlui-mcp v0.1.0
// Then import and use:
import "xmlui-mcp/pkg/xmluimcp"
type MyApp struct {
mcpServer *xmluimcp.MCPServer
}
func NewMyApp() (*MyApp, error) {
// XMLUI repository is automatically downloaded and cached by NewServer
config := xmluimcp.ServerConfig{
HTTPMode: true,
Port: "8080",
}
server, err := xmluimcp.NewServer(config)
if err != nil {
return nil, err
}
return &MyApp{mcpServer: server}, nil
}
func (app *MyApp) Start() error {
app.mcpServer.PrintStartupInfo()
return app.mcpServer.ServeHTTP()
}
```
### Available Methods
- `EnsureXMLUIRepo() (string, error)` - Download and cache XMLUI repository if needed, returns path
- `GetCacheDir() (string, error)` - Get platform-specific cache directory
- `GetRepoDir() (string, error)` - Get cached repository directory path
- `NewServer(config ServerConfig) (*MCPServer, error)` - Create a new server instance
- `ServeStdio() error` - Start server in stdio mode
- `ServeHTTP() error` - Start server in HTTP mode
- `GetTools() []mcp.Tool` - Get available tools
- `GetPrompts() []mcp.Prompt` - Get available prompts
- `GetSessionManager() *SessionManager` - Get session manager
- `PrintStartupInfo()` - Print server information
### Configuration
The `ServerConfig` struct supports:
- `ExampleRoot`: Root directory for examples (optional)
- `ExampleDirs`: Subdirectories within example root (optional)
- `HTTPMode`: Whether to run in HTTP mode
- `Port`: Port for HTTP mode (default: "8080")
- `AnalyticsFile`: Path to analytics file (optional)
Note: The XMLUI repository is automatically downloaded and cached on first use. No manual path configuration is needed.
## API Reference
### ServerConfig
Configuration for the XMLUI MCP server.
```go
type ServerConfig struct {
ExampleRoot string // Optional: root directory for examples
ExampleDirs []string // Optional: subdirectories within example root
HTTPMode bool // Whether to run in HTTP mode
Port string // Port for HTTP mode (default: "8080")
AnalyticsFile string // Path to analytics file (optional)
}
```
Note: The XMLUI repository path is automatically managed by the server and does not need to be specified in the config.
### MCPServer
Main server instance with methods for starting and managing the server.
### SessionManager
Manages multiple user sessions with injected prompts and context.
## Test the server
Agents like Claude, Cursor, and Copilot typically use the server in stdio mode. You can use the server directly that way.
```
npx @modelcontextprotocol/inspector
http://localhost:6274/?MCP_PROXY_AUTH_TOKEN=550d43b6ac5b2881185e81c9c4abdb8115bc90ac3e277d97076bfcc84f4d6288
```
If a browser does not auto-launch, copy/paste that URL. In the inspector, fill in Command and Arguments.
Command: /path/to/xmlui-mcp
Arguments: -e /path/to/example-project
Then click Connect.
## Building from Source
### Library Build
To build just the library:
```bash
go build ./pkg/xmluimcp/...
```
### CLI Build
To build the CLI executable:
```bash
go build -o xmlui-mcp ./cmd/xmlui-mcp
```
### Running Tests
```bash
# Run all tests
go test ./...
# Run specific package tests
go test ./pkg/xmluimcp -v
# Skip network tests (if offline)
SKIP_NETWORK_TESTS=1 go test ./pkg/xmluimcp -v
```
### Development
The project structure is organized as:
```
xmlui-mcp/
├── pkg/xmluimcp/ # Library package
│ ├── cache.go # Platform-specific cache directory resolution
│ ├── repo_downloader.go # GitHub repository download and caching
│ ├── server.go # MCP server implementation
│ ├── session.go # Session management
│ └── utils.go # Utility functions
├── cmd/xmlui-mcp/ # CLI executable
├── server/ # Tool implementations
└── example/ # Library usage examples
```
### How Repository Caching Works
1. **First Run**: When started without a directory argument, the server queries GitHub for the latest `xmlui@<version>` release
2. **Download**: The repository is downloaded as a ZIP file to a temporary directory
3. **Extraction**: The ZIP is extracted and validated
4. **Atomic Move**: Once complete, the repository is atomically moved to the cache directory
5. **Subsequent Runs**: The cached version is used, no re-download needed
The atomic download process ensures that interrupted downloads or crashes don't leave the cache in a broken state.
## Analytics
The server saves logs to enable tracking agent usage patterns and optimizing the tools. Data is saved to `xmlui-mcp-analytics.json`. Use `./analytics-helper.sh` for overviews of what's been captured.
Connection Info
You Might Also Like
everything-claude-code
Complete Claude Code configuration collection - agents, skills, hooks,...
markitdown
MarkItDown-MCP is a lightweight server for converting URIs to Markdown.
servers
Model Context Protocol Servers
servers
Model Context Protocol Servers
Time
A Model Context Protocol server for time and timezone conversions.
Filesystem
Node.js MCP Server for filesystem operations with dynamic access control.