Metadata-Version: 2.4
Name: elements-mcp
Version: 0.1.0
Summary: MCP server for shared Elements project skills and templates.
Author: Elements Team
Requires-Python: >=3.10
Description-Content-Type: text/markdown
Requires-Dist: fastmcp==3.0.0
Provides-Extra: dev
Requires-Dist: pytest>=8.0; extra == "dev"

# elements-mcp

`elements-mcp` is a local MCP server for shared Elements engineering skills and templates. It exposes repository guidance as read-only MCP resources, tools, and prompts so multiple projects can consume the same standards without copying `.github/skills` into every repository.

This project is intended to be published as an internal Python package. Users install the package, configure Codex to start the MCP server, then ask Codex to read project skills and templates through MCP.

中文工程说明见 [README.zh-CN.md](README.zh-CN.md)。

中文安装与使用说明见 [docs/mcp-user-guide-zh.md](docs/mcp-user-guide-zh.md)。

## Current Scopes

Current scope IDs:

```text
ui
partner
```

The `ui` scope currently contains:

```text
ui/
  accessibility-standards/
  api-integration/
  code-quality/
  component-catalog/
  i18n-usage/
  license-knowledge/
  naming-conventions/
  page-structure/
  performance-optimization/
  security-standards/
  ui-component-guidelines/
  ui-standard-layout/
  ui-table-column/
  ui-table-column-filter/
```

The `partner` scope is reserved for Partner-specific engineering skills and templates.

## What The MCP Server Provides

Tools:

- `list_skill_scopes()`
- `list_project_skills(scope: str | None = None)`
- `read_project_skill(scope: str, skill_name: str)`
- `search_project_skills(query: str, scope: str | None = None)`
- `list_skill_templates(scope: str, skill_name: str)`
- `read_skill_template(scope: str, skill_name: str, template_name: str)`

Resources:

- `elements-skill://{scope}/{skill_name}/SKILL.md`
- `elements-template://{scope}/{skill_name}/{template_name}`

Prompts:

- `apply_project_skill(scope: str, skill_name: str, task: str)`

## Maintainer Setup

Use this when developing or publishing `elements-mcp`.

```powershell
cd C:\Code\elements-mcp
python -m venv .venv
.\.venv\Scripts\python.exe -m pip install -e ".[dev]"
```

Run tests:

```powershell
.\.venv\Scripts\python.exe -m pytest
```

Run the MCP server directly:

```powershell
.\.venv\Scripts\python.exe -m elements_mcp.server
```

The direct server command is a long-running stdio MCP process. In normal usage, Codex starts and manages it.

## Publishing A Package

Install packaging tools:

```powershell
.\.venv\Scripts\python.exe -m pip install build twine
```

Build source distribution and wheel:

```powershell
.\.venv\Scripts\python.exe -m build
```

Expected output:

```text
dist/elements_mcp-0.1.0.tar.gz
dist/elements_mcp-0.1.0-py3-none-any.whl
```

Publish to the company Python package feed:

```powershell
.\.venv\Scripts\python.exe -m twine upload --repository-url https://your-private-pypi.example/repository/pypi-internal/ dist/*
```

Replace the URL with the actual internal PyPI-compatible repository.

## User Installation

Recommended user setup is a dedicated virtual environment. This keeps the MCP server dependency tree separate from system Python and project-specific frontend tooling.

```powershell
mkdir C:\Tools\elements-mcp
cd C:\Tools\elements-mcp
python -m venv .venv
.\.venv\Scripts\python.exe -m pip install --index-url https://your-private-pypi.example/repository/pypi-internal/simple elements-mcp==0.1.0
```

If the package is shared as a wheel file before the internal package feed is ready:

```powershell
mkdir C:\Tools\elements-mcp
cd C:\Tools\elements-mcp
python -m venv .venv
.\.venv\Scripts\python.exe -m pip install C:\Path\To\elements_mcp-0.1.0-py3-none-any.whl
```

Verify the package can be imported:

```powershell
.\.venv\Scripts\python.exe -c "from elements_mcp.registry import SkillRegistry; print(SkillRegistry().list_scopes())"
```

Expected output includes:

```text
['partner', 'ui']
```

Verify the server can be created:

```powershell
.\.venv\Scripts\python.exe -c "from elements_mcp.server import create_server; print(create_server().name)"
```

Expected output:

```text
Elements MCP
```

## Codex Configuration For Users

Add the MCP server to the user's Codex config file.

Typical Windows path:

```text
C:\Users\<user>\.codex\config.toml
```

Recommended configuration when installed into `C:\Tools\elements-mcp\.venv`:

```toml
[mcp_servers.elements]
command = "C:\\Tools\\elements-mcp\\.venv\\Scripts\\python.exe"
args = ["-m", "elements_mcp.server"]
cwd = "C:\\Tools\\elements-mcp"
startup_timeout_sec = 20
tool_timeout_sec = 60
```

Restart Codex after editing the config.

Check connection in Codex:

```text
/mcp
```

Or from a terminal:

```powershell
codex mcp list
```

Expected result: an MCP server named `elements` is listed and available.

## Business Repository Guidance

Each business repository should tell agents to use this MCP server. Add a short note to that repository's `AGENTS.md`.

Example:

```markdown
## Project Skills

This repository uses the `elements` MCP server for shared project skills and templates.

- For UI work, use scope `ui`.
- For Partner work, use scope `partner`.
- Before editing UIStandardLayout pages, read `ui-standard-layout`.
- Before adding API services, read `api-integration`.
- Before adding table cell renderers, read `ui-table-column`.
- Before adding table filters, read `ui-table-column-filter`.
- Do not hardcode user-visible strings; read `i18n-usage`.
```

## Example Codex Usage

After the MCP server is connected, users can ask Codex:

```text
Use the elements MCP server. Read the ui-standard-layout skill from scope ui and the page-shell template before changing this page.
```

Useful MCP calls for agents:

```text
list_skill_scopes()
list_project_skills(scope="ui")
read_project_skill(scope="ui", skill_name="ui-standard-layout")
list_skill_templates(scope="ui", skill_name="ui-standard-layout")
read_skill_template(scope="ui", skill_name="ui-standard-layout", template_name="page-shell.template.mdx")
```

## Updating Users To A New Version

Publish a new package version, then users upgrade their dedicated environment:

```powershell
C:\Tools\elements-mcp\.venv\Scripts\python.exe -m pip install --upgrade --index-url https://your-private-pypi.example/repository/pypi-internal/simple elements-mcp==0.2.0
```

Restart Codex after upgrading.

If a user needs to roll back:

```powershell
C:\Tools\elements-mcp\.venv\Scripts\python.exe -m pip install --force-reinstall --index-url https://your-private-pypi.example/repository/pypi-internal/simple elements-mcp==0.1.0
```

## Adding New Skills

Add shared content under:

```text
src/elements_mcp/content/skills/<scope>/<skill-name>/
```

Required:

```text
SKILL.md
```

Optional:

```text
templates/*.template.mdx
```

Example:

```text
src/elements_mcp/content/skills/ui/new-skill/
  SKILL.md
  templates/
    example.template.mdx
```

Then run:

```powershell
.\.venv\Scripts\python.exe -m pytest
.\.venv\Scripts\python.exe -m build
```

## Content Rules

- Keep this server read-only.
- Do not add tools that write files or execute shell commands.
- Add new shared project guidance under `src/elements_mcp/content/skills/<scope>/<skill-name>`.
- Each skill directory must contain `SKILL.md`.
- Optional templates belong under `templates/` inside the skill directory.
- Use safe names with letters, numbers, dots, underscores, and hyphens only.
- Pin released package versions for users, such as `elements-mcp==0.1.0`.

## Troubleshooting

`No module named elements_mcp`:

The Codex config is pointing at a Python environment where `elements-mcp` is not installed. Use the Python path from the dedicated virtual environment.

`No module named fastmcp`:

The package was not installed with dependencies. Reinstall with `pip install elements-mcp==<version>` instead of copying source files manually.

`/mcp` does not show `elements`:

Restart Codex after editing `config.toml`, then check that the configured `command` path exists.

Server starts then exits:

Run the configured command manually:

```powershell
C:\Tools\elements-mcp\.venv\Scripts\python.exe -m elements_mcp.server
```

If it reports import errors, reinstall the package in that virtual environment.

## References

- Codex MCP configuration: `~/.codex/config.toml`, `[mcp_servers.<name>]`, `/mcp`, and `codex mcp list`
- FastMCP packaging dependency: `fastmcp==3.0.0`
