Metadata-Version: 2.4
Name: elements-mcp
Version: 0.1.6
Summary: MCP server for shared Elements project skills 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

`elements-mcp` is a read-only MCP server for shared Elements engineering skills and templates. It packages project guidance as MCP tools, resources, and prompts so coding agents can consume the same standards across repositories.

Chinese documentation by audience:

- Maintainers: [Project maintenance and release guide](README.zh-CN.md)
- Users: [Installation and MCP client setup guide](docs/mcp-user-guide-zh.md)

## What It Provides

Tools:

- `get_project_guidance(task: str, max_skills: int = 3)`
- `list_project_skills()`
- `read_project_skill(skill_name: str)`
- `search_project_skills(query: str)`
- `list_skill_templates(skill_name: str)`
- `read_skill_template(skill_name: str, template_name: str)`

Resources:

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

Prompts:

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

## Recommended Host Flow

The current project, IDE integrations, or other AI hosts should call `get_project_guidance` automatically with the user's original task before asking the AI to code. Users should not need to type MCP tool names.

If `matched` is `true`, inject the returned `guidance` into the AI request. If `matched` is `false`, continue with normal coding behavior and do not invent project-specific rules.

## Maintainer Quick Start

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

Run the MCP server directly:

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

Build distributions:

```powershell
.\.venv\Scripts\python.exe -m pip install -U build twine
.\.venv\Scripts\python.exe -m build
.\.venv\Scripts\python.exe -m twine check dist/*
```

## Content Layout

Runtime content follows the MCP concepts:

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

Keep this server read-only. Do not add tools that write files, delete files, execute shell commands, or read arbitrary local paths.
