Metadata-Version: 2.4
Name: elements-mcp
Version: 0.1.15
Summary: MCP server for shared Elements engineering standards, domain knowledge, skills, prompts, and templates.
Author: Andy Li
Requires-Python: >=3.10
Description-Content-Type: text/markdown
Requires-Dist: fastmcp==3.2.4
Provides-Extra: dev
Requires-Dist: pytest>=8.0; extra == "dev"

# elements-mcp Project Guide

`elements-mcp` is a read-only MCP server that packages shared Elements engineering standards, skills, and templates as a Python package for Codex, GitHub Copilot, and other AI coding agents.

This document is for maintainers. It describes the project structure, development verification, release flow, and content maintenance rules. For user installation and MCP client setup, see [docs/install-elements-mcp-user-guide-zh.md](docs/install-elements-mcp-user-guide-zh.md).

## Goals and Boundaries

Goals:

- Consolidate engineering standards, domain knowledge, skills, prompts, and templates shared by multiple business repositories into reusable MCP content.
- Distribute the Python package through PyPI so users get the latest version by default, while still allowing pinned versions when needed.
- Expose packaged skills/templates and reusable prompts through MCP tools, resources, and prompts.
- Keep the server read-only to reduce security risk.

Boundaries:

- The server may list, search, and read packaged skills/templates.
- The server must not write files, delete files, execute shell commands, install dependencies, or read paths outside the package.
- Any future write-capable or execution-capable tools require a separate security design.

## Repository Layout

```text
elements-mcp/
  README.md
  README.zh-CN.md
  MANIFEST.in
  pyproject.toml
  docs/
    install-elements-mcp-user-guide-zh.md
  scripts/
    install_elements_mcp.py
    publish-pypi.ps1
    pypi-publish.env.example.ps1
    update-package-metadata.ps1
  src/
    elements_mcp/
      __init__.py
      server.py
      tools/
      resources/
        registry.py
        handlers.py
        content/
          skills/
            ui-standard-layout/
            api-integration/
      prompts/
        registry.py
        handlers.py
        content/
  tests/
```

## Key File Responsibilities

- `pyproject.toml`: Python package configuration, including package name, version, dependencies, entry point, package data, and pytest configuration.
- `MANIFEST.in`: source distribution rules; keeps runtime content and excludes `docs/`.
- `src/elements_mcp/tools/`: MCP tool registration and implementations.
- `src/elements_mcp/resources/`: MCP resource registration, skills/templates index, and packaged resource content.
- `src/elements_mcp/prompts/`: MCP prompt registration, prompt index, and packaged prompt content.
- `src/elements_mcp/server.py`: FastMCP server assembly layer that registers tools, resources, and prompts.
- `tests/`: development and pre-release verification; not a user runtime dependency.
- `docs/install-elements-mcp-user-guide-zh.md`: user installation and client setup guide.
- `scripts/install_elements_mcp.py`: cross-platform isolated-install helper; installs to the fixed `Tools\elements-mcp` directory and uses `uv` to install the latest `elements-mcp` from PyPI.
- `scripts/publish-pypi.ps1`: release script; uses `uv` to prepare the project-root `.venv`, then runs tests, builds, checks, and uploads.
- `scripts/pypi-publish.env.example.ps1`: local PyPI token configuration template.
- `scripts/update-package-metadata.ps1`: maintenance script for synchronizing package name and version text.

## MCP Contract

Tools:

```text
get_project_guidance(task, max_skills=3)
list_project_skills()
read_project_skill(skill_name)
search_project_skills(query)
list_skill_templates(skill_name)
read_skill_template(skill_name, template_name)
```

Resources:

```text
elements-skill://i18n-usage/SKILL.md
elements-skill://naming-conventions/SKILL.md
elements-skill://page-structure/SKILL.md
elements-skill://{skill_name}/SKILL.md
elements-template://{skill_name}/{template_name}
```

The three concrete `elements-skill://.../SKILL.md` resources are core static
skills that show up in `list_resources()`. The parameterized skill/template URIs
remain available for reading any packaged skill or template by name.

Prompts:

```text
apply_project_skill(skill_name, task)
check-i18n
create-filter-table
```

All tools should be marked as read-only, non-destructive, idempotent, and closed-world.

The current project, IDE integration, or other AI host should automatically call `get_project_guidance(userMessage)` after the user starts a coding request. Users should not need to type MCP tool names manually.

When `matched=true`, the caller should inject `guidance` into the AI request. When `matched=false`, continue the normal coding flow, do not block the user request, and do not invent nonexistent project rules.

## Content Maintenance

Add skills under:

```text
src/elements_mcp/resources/content/skills/
```

Add a skill:

```text
src/elements_mcp/resources/content/skills/<skill-name>/
  SKILL.md
  templates/
    example.template.mdx
```

Add prompts:

```text
src/elements_mcp/prompts/content/<prompt-name>.prompt.md
```

Rules:

- `SKILL.md` is required.
- `templates/` is optional.
- Skill and template file names should use letters, digits, dots, underscores, and hyphens.
- Do not use spaces, Chinese file names, path separators, or special characters.
- Put long reusable examples in `templates/*.template.mdx` instead of making a single `SKILL.md` too long.

## Local Development

Maintainers should use `uv` and the project-root `.venv` as the development, testing, and publishing environment. Do not install development dependencies into the global Python environment or user site-packages.

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

Run tests:

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

Run the server:

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

Verify the registry:

```powershell
.\.venv\Scripts\python.exe -c "from elements_mcp.resources.registry import SkillRegistry; print([skill.name for skill in SkillRegistry().list_skills()])"
```

Verify the server:

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

## Build and Publish

If code or packaged content changes, update the version before publishing a new package and rebuild clean distribution artifacts.

Publishing also uses only the project-root `.venv`. `scripts\publish-pypi.ps1` uses `uv` to create or update that environment, then calls `.\.venv\Scripts\python.exe` to run tests, build, check, and upload. To prepare manually, run:

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

For normal publishing, run the one-step script. The script cleans `dist/`, runs tests, builds distributions, runs `twine check`, and uploads:

```powershell
.\scripts\publish-pypi.ps1
```

Publish to a non-default repository:

```powershell
.\scripts\publish-pypi.ps1 -Repository <repository-name>
```

Expected artifacts:

```text
dist/elements_mcp-<version>.tar.gz
dist/elements_mcp-<version>-py3-none-any.whl
```

If you need to troubleshoot build or publish issues, run the main script steps manually:

```powershell
Remove-Item -LiteralPath dist -Recurse -Force -ErrorAction SilentlyContinue
.\.venv\Scripts\python.exe -m pytest
.\.venv\Scripts\python.exe -m build
.\.venv\Scripts\python.exe -m twine check dist/*
```

When publishing a new version:

1. Update `version` in `pyproject.toml`.
2. If needed, run `.\scripts\update-package-metadata.ps1 -Version <version> -WhatIf` to preview version text updates, then rerun without `-WhatIf`.
3. Confirm `scripts/pypi-publish.env.ps1` is configured with a PyPI token and keeps `TWINE_USERNAME` as `__token__`.
4. Run `.\scripts\publish-pypi.ps1`; the script cleans old `dist/`, runs tests, builds, runs `twine check`, and uploads to PyPI.
5. If the script fails midway, fix the failure and rerun the same command.
6. Confirm the new version appears at https://pypi.org/project/elements-mcp/.
7. Verify installation in a clean virtual environment:

```powershell
uv venv C:\Temp\elements-mcp-publish-check
uv pip install --python C:\Temp\elements-mcp-publish-check\Scripts\python.exe elements-mcp==<version>
C:\Temp\elements-mcp-publish-check\Scripts\python.exe -c "from elements_mcp.server import create_server; print(create_server().name)"
```

8. Tell users who use `uvx` to restart their MCP client. If they use a fixed virtual environment, tell them to rerun the isolated-environment update command from the user guide. For rollback or staged verification, specify `elements-mcp==<version>`.

`src/elements_mcp/__init__.py` reads `__version__` from installed package metadata, so it does not need separate manual version maintenance.

## Documentation Roles

- `README.md`: English version of this maintainer guide.
- `README.zh-CN.md`: Chinese version of this maintainer guide.
- `docs/install-elements-mcp-user-guide-zh.md`: Chinese user guide for installing `elements-mcp`, configuring MCP clients, and troubleshooting connection issues.
