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.

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

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:

get_elements_diagnostics(task="", max_skills=5)
get_project_guidance(task, max_skills=3, profile="summary")
list_project_skills()
read_project_skill(skill_name)
search_project_skills(query)
list_skill_templates(skill_name)
read_skill_template(skill_name, template_name)
list_skill_references(skill_name)
read_skill_reference(skill_name, reference_name)

Resources:

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}
elements-reference://{skill_name}/{reference_name}

The three concrete elements-skill://.../SKILL.md resources are core static skills that show up in list_resources(). Parameterized skill, template, and reference URIs remain available for reading packaged content by name.

Prompts:

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, profile="summary") after the user starts a coding request. Users should not need to type MCP tool names manually. Callers should read the routed skill/template resource URIs only when their details are needed.

summary is the default and the only profile intended for automatic agent preflight. Agents should read routed resource URIs for details instead of automatically escalating profiles. primary and full remain available only for explicit deep retrieval, compatibility checks, and diagnostics.

When matched=true, the caller should use route as the canonical structured result, present every required_inputs item before implementation, and use guidance only as a compact compatibility rendering. required_template remains a metadata-only alias for the first required input during migration. 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:

src/elements_mcp/resources/content/skills/

Add a skill:

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

Add prompts:

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

Rules:

• SKILL.md is required.
• templates/ is optional.
• references/ is optional and should hold full guides, deep recipes, and other details retrieved intentionally.
• 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.
• Every packaged skill must declare metadata.routing.kind as specialized or supporting.
• Gated skills must declare metadata.intake.required: true and a valid metadata.intake.template.
• Keep SKILL.md entrypoints at or below 10 KB when possible. Content above 10 KB is a warning; content above 15 KB requires explicit review.

Supported metadata example:

metadata:
  routing:
    kind: specialized
  intake:
    required: true
    template: request-input.template.yaml

get_elements_diagnostics reports metadata support, content sizes, catalog names, and optional raw routing scores. The project intentionally keeps the validated frontmatter subset and cached linear search: the current small corpus does not justify a new YAML dependency or precomputed search index.

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.

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

Run tests:

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

Run the server:

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

Verify the registry:

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

Verify the server:

.\.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:

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:

.\scripts\publish-pypi.ps1

Publish to a non-default repository:

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

Expected artifacts:

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:

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:

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.