project-mcp

Project Development MCP Server

A FastMCP server that exposes predefined artifacts (templates, configs, code snippets, assets) as Resources and project lifecycle operations as Tools. Use it from Cursor or any MCP client to create, update, deploy, debug, test, monitor, and configure projects with minimal token usage.

Recommended: HTTP transport. Run the server once; all clients (Cursor, other IDEs, CLIs) connect to the same URL. One process, shared use, no per-client spawn.

Setup

Option A: Nix + devenv (recommended)

With Nix and devenv installed:

cd project-mcp
devenv up

This installs Python and uv, runs uv sync, and starts the MCP server on HTTP at http://localhost:8000/mcp. Leave it running; point Cursor and other clients at that URL. Use direnv allow if you use direnv (optional for devenv up).

Option B: uv only

• Python 3.10+
• uv
• FastMCP 3.x (installed via uv)

cd project-mcp
uv sync

Running the server

HTTP (recommended) — one server for all clients:

# With devenv (starts HTTP server)
devenv up

# Or with uv only (HTTP is the default)
uv run python server.py

Server base URL: http://localhost:8000/mcp (port 8000 unless you set MCP_PORT). Connect Cursor and other clients to this URL; no need for each client to run the server. When using HTTP, a /health endpoint returns {"status": "ok"} for load balancers or k8s probes.

Stdio (alternative) — Cursor or another client runs the server as a subprocess (one process per client). Set MCP_TRANSPORT=stdio or use the fastmcp CLI:

MCP_TRANSPORT=stdio uv run python server.py
# or
uv run fastmcp run fastmcp.json

Use stdio if you prefer zero “run the server” step and only one client.

Configuration

• PROJECT_MCP_ROOT — Root directory for project paths (default: current working directory). All tool paths (target_path, project_path, path) must resolve under this root; path traversal (e.g. ../) is rejected. Set this to your workspace or a dedicated projects directory to scope and secure where the server can read/write. At startup, the server warns if this is set but not a directory or missing.
• PROJECT_MCP_ALLOWED_COMMANDS — Comma-separated list of command prefixes allowed by run_command (e.g. python,npm,uv). If unset, defaults to: python, npm, npx, uv, pip, node, pytest, make.
• MCP_TRANSPORT — http (default) or stdio.
• MCP_PORT — Port for HTTP (default: 8000).
• LOG_LEVEL — Logging level (default: INFO). Set to DEBUG for more verbose tool logs.

Running tests

Install dev dependencies (pytest, ruff), then run the test suite:

uv sync --extra dev
uv run pytest tests/ -v

To run linting and format checks (same as CI):

uv run ruff check .
uv run ruff format --check .

Cursor integration

HTTP (recommended): Run the server once (e.g. devenv up or the HTTP command above), then add the server in Cursor by URL. Example MCP config (e.g. in Cursor Settings → MCP or .cursor/mcp.json):

{
  "mcpServers": {
    "project-dev": {
      "url": "http://localhost:8000/mcp"
    }
  }
}

If your Cursor version uses a different shape (e.g. transport: "sse" with a separate url), see Cursor + FastMCP. Use your actual host/port if not localhost. All Cursor windows and other clients can use the same running server.

Stdio (alternative): Cursor runs the server itself. In MCP settings use a command instead of a URL:

{
  "mcpServers": {
    "project-dev": {
      "command": "uv",
      "args": ["run", "fastmcp", "run", "fastmcp.json"],
      "cwd": "/absolute/path/to/project-mcp"
    }
  }
}

Replace /absolute/path/to/project-mcp with the real path.

Artifacts and URI scheme

Predefined content is organized by context first (folder under artifacts/), then type (folder under each context). Context is a flexible grouping—maintainers choose the strategy that fits their needs (e.g. by technology, project type, or other axes).

URI pattern: artifact://{context}/{type}/{path}

| Part | Purpose | Examples | | --------- | ------- | -------- | | context | Grouping chosen by maintainer | default (generic), fastapi, react, internal-admin, data-pipeline | | type | Kind of artifact under that context | templates, configs, snippets, assets, components, iac | | path | Relative path under context/type | fastapi-app, pyproject.toml, Button.tsx |

Context examples:

• By technology: fastapi, react, aws, gcp
• By project type: internal-admin, data-pipeline, research-notebook, app-documentation
• default: generic, stack-agnostic artifacts only

URI examples:

• artifact://default/configs/pyproject.toml — generic Python config
• artifact://default/snippets/hello.py — generic hello snippet
• artifact://fastapi/templates/fastapi-app — FastAPI app template
• artifact://react/templates/react-component.tsx — React component template
• artifact://data-pipeline/configs/dag.yaml — data pipeline DAG config

Add new contexts by adding a folder under artifacts/; add new types by adding a folder under a context. No server code changes required. Use Resources to read these URIs on demand so the LLM does not hold large blobs in context.

Tools

| Tool | Description | | ---------------- | ----------------------------------------------------------------- | | list_artifacts | List available artifacts (optionally filter by context/type). Returns JSON with uri per artifact. | | create_project | Create project from a template; use context to pick the group. Optional variables for {{key}} substitution. | | read_file | Read a file at path (under project root). | | list_directory | List directory contents at path (one level). | | search_files | Search for regex pattern in project files; optional include/exclude globs. | | edit_file | Replace old_string with new_string in file (first or all). | | write_file | Write or overwrite a file under the project root. | | run_tests | Run tests (pytest or npm test). | | deploy | Run deploy (Makefile, npm run deploy, or custom script). | | run_command | Run an allowed command in project dir (python, npm, uv, etc.). | | status | Project status and detected type. | | get_logs | Recent log content from .log files. | | get_config | Read config key (e.g. name, version) from pyproject/package.json. | | update_config | Update name or version in pyproject.toml or package.json. |

All paths are validated against PROJECT_MCP_ROOT to prevent path traversal.

Usage examples

From an MCP client (e.g. Cursor), you can call tools and read resources like this:

Discover artifacts: Call list_artifacts() (or list_artifacts(context="fastapi")) to get a JSON list of artifact URIs, then read any via the Resource artifact://{context}/{type}/{path}.

Create a FastAPI project: ``text create_project(template_id="fastapi-app", target_path="./my-api", context="fastapi") ``

Create a project with template variables: If the template contains {{project_name}} or {{version}}, pass them in: ``text create_project(template_id="var-test", target_path="./my-app", context="default", variables={"project_name": "MyApp", "version": "1.0"}) ``

Write a file: write_file(path="src/main.py", content="print('hello')")

Project status: status(project_path=".") — returns detected type (Python/Node) and top-level listing.

Run tests: run_tests(project_path=".") — runs pytest or npm test based on project type.

Project layout

project-mcp/
├── server.py           # FastMCP app and registration
├── path_util.py        # Path validation helpers
├── artifact_loader.py  # Artifact discovery and read (type/context/path)
├── fastmcp.json        # FastMCP project config
├── devenv.nix          # Nix + devenv (packages, process)
├── devenv.yaml         # Devenv inputs
├── .envrc              # direnv: use devenv
├── pyproject.toml
└── artifacts/          # Client-facing content: artifact://{context}/{type}/{path}
    ├── default/       # generic, stack-agnostic only
    │   ├── configs/   # pyproject.toml, tsconfig.json, Dockerfile
    │   ├── snippets/  # hello.py
    │   └── assets/    # placeholder.svg
    ├── fastapi/       # context: technology
    │   └── templates/ # fastapi-app
    ├── react/         # context: technology
    │   └── templates/ # react-component.tsx
    # Add contexts as needed: internal-admin/, data-pipeline/, aws/, gcp/, etc.

License

MIT.