ucpcore-server 0.1.0__tar.gz

ucpcore_server-0.1.0/.dockerignore

@@ -0,0 +1,8 @@
+.venv
+__pycache__
+*.egg-info
+.pytest_cache
+dist
+tests
+Dockerfile
+.dockerignore

ucpcore_server-0.1.0/.gitignore

@@ -0,0 +1,6 @@
+node_modules/
+package-lock.json
+.venv/
+__pycache__/
+.pytest_cache/
+.DS_Store

ucpcore_server-0.1.0/Dockerfile

@@ -0,0 +1,38 @@
+# syntax=docker/dockerfile:1
+
+# --- build stage: build the wheel, keep build tooling out of the image -------
+FROM python:3.12-slim AS build
+
+WORKDIR /build
+COPY pyproject.toml README.md ./
+COPY src ./src
+RUN pip install --no-cache-dir build && python -m build --wheel --outdir /dist
+
+# --- runtime stage ------------------------------------------------------------
+FROM python:3.12-slim
+
+LABEL org.opencontainers.image.title="ucp-server" \
+      org.opencontainers.image.description="Self-hosted UCP generation service: REST + MCP (Streamable HTTP)" \
+      org.opencontainers.image.url="https://ucpcore.org" \
+      org.opencontainers.image.source="https://github.com/ucpcore/ucp" \
+      org.opencontainers.image.licenses="Apache-2.0" \
+      org.opencontainers.image.vendor="UCP contributors"
+
+RUN useradd --create-home --uid 1000 ucp
+
+COPY --from=build /dist/*.whl /tmp/
+RUN pip install --no-cache-dir /tmp/*.whl && rm /tmp/*.whl
+
+# 0.0.0.0 is deliberate inside the container: the container boundary is the
+# isolation; publish the port consciously (see README, Security).
+ENV UCP_SERVER_HOST=0.0.0.0 \
+    UCP_SERVER_PORT=8080 \
+    UCP_CACHE_DIR=/home/ucp/.cache/ucp-server
+
+USER ucp
+EXPOSE 8080
+
+HEALTHCHECK --interval=30s --timeout=5s --start-period=10s --retries=3 \
+  CMD ["python", "-c", "import urllib.request; urllib.request.urlopen('http://127.0.0.1:8080/healthz', timeout=4)"]
+
+ENTRYPOINT ["ucp-server"]

ucpcore_server-0.1.0/PKG-INFO

@@ -0,0 +1,190 @@
+Metadata-Version: 2.4
+Name: ucpcore-server
+Version: 0.1.0
+Summary: Self-hosted UCP server: generate Universal Context Packages from GitHub/Jira over REST and MCP (Streamable HTTP). One command to run.
+Project-URL: Specification, https://github.com/ucpcore/ucp
+Project-URL: Homepage, https://ucpcore.org
+Author: UCP contributors
+License-Expression: Apache-2.0
+Keywords: context,context-engineering,llm,mcp,server,ucp
+Requires-Python: >=3.11
+Requires-Dist: fastapi>=0.115
+Requires-Dist: fastmcp>=2.3
+Requires-Dist: httpx>=0.27
+Requires-Dist: pydantic-settings>=2.4
+Requires-Dist: pydantic>=2.7
+Requires-Dist: pyucp>=0.1.0
+Requires-Dist: ucp-gen>=0.3.0
+Requires-Dist: uvicorn>=0.30
+Provides-Extra: dev
+Requires-Dist: pytest-asyncio>=0.23; extra == 'dev'
+Requires-Dist: pytest>=8; extra == 'dev'
+Description-Content-Type: text/markdown
+
+# ucp-server — self-hosted UCP generation service
+
+One process, two interfaces. Point it at GitHub/Jira credentials and get
+[Universal Context Packages](https://ucpcore.org) on demand:
+
+- **REST API** (`/v1`) — generate and fetch packages with `curl` or any HTTP client;
+- **MCP over Streamable HTTP** (`/mcp`) — plug it straight into Cursor,
+  Claude Code, or any MCP-capable agent.
+
+Configuration is environment-only (12-factor), generated packages are cached
+on disk with a TTL, and authentication is one env var away. Install it,
+start it, forget it.
+
+> PyPI package name: **`ucpcore-server`** (the name `ucp-server` was taken).
+> The command it installs is still `ucp-server`.
+
+## Quickstart
+
+### Docker (one command)
+
+```bash
+docker run --rm -p 8080:8080 -e GITHUB_TOKEN=ghp_yourtoken \
+  ghcr.io/ucpcore/ucp-server:latest
+```
+
+### uvx / pipx (no Docker)
+
+```bash
+uvx --from ucpcore-server ucp-server
+# or: pipx run --spec ucpcore-server ucp-server
+```
+
+Then generate a package from any public GitHub issue:
+
+```bash
+curl -s -X POST http://localhost:8080/v1/generate \
+  -H 'Content-Type: application/json' \
+  -d '{"source": "github", "ref": "pallets/flask#5961"}' | head
+```
+
+Interactive API docs: <http://localhost:8080/docs>.
+
+## Connect an agent (MCP)
+
+The MCP endpoint speaks Streamable HTTP at `http://localhost:8080/mcp`.
+
+Cursor / Claude Code (`mcp.json`):
+
+```json
+{
+  "mcpServers": {
+    "ucp": {
+      "url": "http://localhost:8080/mcp"
+    }
+  }
+}
+```
+
+If the server runs with `UCP_SERVER_API_KEY`, add the header:
+
+```json
+{
+  "mcpServers": {
+    "ucp": {
+      "url": "http://localhost:8080/mcp",
+      "headers": { "Authorization": "Bearer YOUR_KEY" }
+    }
+  }
+}
+```
+
+Tools exposed:
+
+| Tool | Purpose |
+|---|---|
+| `generate_context(source, ref, llm=False)` | Build a UCP from a GitHub issue (`owner/repo#123`) or Jira ticket (`PROJ-123`) |
+| `list_contexts()` | List cached packages: id, entity, title, freshness |
+| `get_context(id)` | Full UCP JSON for a cached package |
+| `get_context_markdown(id, token_budget?)` | Canonical Markdown rendering (SPEC §7), optionally truncated by salience |
+
+## REST API
+
+| Method & path | Purpose |
+|---|---|
+| `POST /v1/generate` | Generate a package. Body: `{"source": "github"\|"jira", "ref": "...", "llm": false, "since": null, "audience": null}`. Returns the UCP JSON; headers `X-UCP-Package-Id` and `X-UCP-Cache: hit\|miss`. |
+| `GET /v1/packages` | Cached packages: id, title, entity, generated_at |
+| `GET /v1/packages/{id}` | Full UCP JSON |
+| `GET /v1/packages/{id}/markdown?token_budget=1500` | Canonical Markdown rendering |
+| `GET /healthz`, `GET /readyz` | Liveness / readiness probes (never authenticated) |
+| `GET /docs`, `GET /openapi.json` | OpenAPI documentation |
+
+Errors are RFC 9457 problem documents (`application/problem+json`):
+
+```json
+{"type": "https://ucpcore.org/problems/invalid-ref", "title": "Invalid Reference",
+ "status": 400, "detail": "invalid GitHub reference 'x': expected owner/repo#number..."}
+```
+
+Examples:
+
+```bash
+# Jira (needs JIRA_* env on the server)
+curl -s -X POST http://localhost:8080/v1/generate \
+  -H 'Content-Type: application/json' \
+  -d '{"source": "jira", "ref": "PROJ-123"}'
+
+# LLM-enhanced (needs UCP_LLM_* env on the server)
+curl -s -X POST http://localhost:8080/v1/generate \
+  -H 'Content-Type: application/json' \
+  -d '{"source": "github", "ref": "microsoft/vscode#519", "llm": true}'
+
+# Rendered Markdown under a token budget
+curl -s "http://localhost:8080/v1/packages/github-pallets-flask-5961/markdown?token_budget=1500"
+```
+
+## Configuration
+
+Everything is optional; the server starts with zero configuration and
+reports clearly when a credential is missing for a requested source.
+
+| Variable | Default | Purpose |
+|---|---|---|
+| `UCP_SERVER_HOST` | `127.0.0.1` (Docker image: `0.0.0.0`) | Bind address |
+| `UCP_SERVER_PORT` | `8080` | Bind port |
+| `UCP_SERVER_API_KEY` | *(unset — auth disabled)* | When set, all endpoints except health probes require `Authorization: Bearer <key>` |
+| `UCP_CACHE_DIR` | `~/.cache/ucp-server` | Disk cache for generated packages |
+| `UCP_CACHE_TTL` | `900` (15 min) | Cache TTL in seconds; `0` disables caching |
+| `GITHUB_TOKEN` / `GH_TOKEN` | *(unset)* | GitHub token (public issues work without it, at a low rate limit) |
+| `JIRA_BASE_URL` | *(unset)* | e.g. `https://yourcompany.atlassian.net` |
+| `JIRA_EMAIL` | *(unset)* | Jira Cloud email (Basic auth); omit for Server/DC PAT |
+| `JIRA_API_TOKEN` | *(unset)* | Jira API token or PAT |
+| `UCP_LLM_BASE_URL` | `https://api.openai.com/v1` | OpenAI-compatible endpoint for `llm: true` |
+| `UCP_LLM_API_KEY` | *(unset)* | LLM API key (falls back to `OPENAI_API_KEY`) |
+| `UCP_LLM_MODEL` | `gpt-4o-mini` | LLM model name |
+| `UCP_LOG_JSON` | `false` | `1`/`true` switches to JSON-lines logs |
+| `UCP_LOG_LEVEL` | `INFO` | Log level |
+
+## Security
+
+- **Set `UCP_SERVER_API_KEY` for any non-localhost deployment.** Without it
+  anyone who can reach the port can spend your GitHub/Jira/LLM quota. The
+  key is compared in constant time; health probes stay open for orchestrators.
+- **Bind is `127.0.0.1` by default** when run directly. The Docker image
+  sets `UCP_SERVER_HOST=0.0.0.0` deliberately — the container boundary is
+  the isolation there; publish the port consciously (`-p 127.0.0.1:8080:8080`
+  keeps it local).
+- **No client-supplied URLs.** Clients pass references (`owner/repo#123`,
+  `PROJ-123`) to the two predefined connectors; the server never fetches an
+  arbitrary URL on a client's behalf (no SSRF surface).
+- Request bodies are limited to 64 KiB and validated strictly (unknown
+  fields rejected). Tokens are masked in logs. The Docker image runs as a
+  non-root user.
+
+## Development
+
+```bash
+python3 -m venv .venv && . .venv/bin/activate
+pip install -e ".[dev]"
+pytest
+```
+
+Docker image:
+
+```bash
+docker build -t ucp-server .
+docker run --rm -p 8080:8080 ucp-server
+```

ucpcore_server-0.1.0/README.md

@@ -0,0 +1,167 @@
+# ucp-server — self-hosted UCP generation service
+
+One process, two interfaces. Point it at GitHub/Jira credentials and get
+[Universal Context Packages](https://ucpcore.org) on demand:
+
+- **REST API** (`/v1`) — generate and fetch packages with `curl` or any HTTP client;
+- **MCP over Streamable HTTP** (`/mcp`) — plug it straight into Cursor,
+  Claude Code, or any MCP-capable agent.
+
+Configuration is environment-only (12-factor), generated packages are cached
+on disk with a TTL, and authentication is one env var away. Install it,
+start it, forget it.
+
+> PyPI package name: **`ucpcore-server`** (the name `ucp-server` was taken).
+> The command it installs is still `ucp-server`.
+
+## Quickstart
+
+### Docker (one command)
+
+```bash
+docker run --rm -p 8080:8080 -e GITHUB_TOKEN=ghp_yourtoken \
+  ghcr.io/ucpcore/ucp-server:latest
+```
+
+### uvx / pipx (no Docker)
+
+```bash
+uvx --from ucpcore-server ucp-server
+# or: pipx run --spec ucpcore-server ucp-server
+```
+
+Then generate a package from any public GitHub issue:
+
+```bash
+curl -s -X POST http://localhost:8080/v1/generate \
+  -H 'Content-Type: application/json' \
+  -d '{"source": "github", "ref": "pallets/flask#5961"}' | head
+```
+
+Interactive API docs: <http://localhost:8080/docs>.
+
+## Connect an agent (MCP)
+
+The MCP endpoint speaks Streamable HTTP at `http://localhost:8080/mcp`.
+
+Cursor / Claude Code (`mcp.json`):
+
+```json
+{
+  "mcpServers": {
+    "ucp": {
+      "url": "http://localhost:8080/mcp"
+    }
+  }
+}
+```
+
+If the server runs with `UCP_SERVER_API_KEY`, add the header:
+
+```json
+{
+  "mcpServers": {
+    "ucp": {
+      "url": "http://localhost:8080/mcp",
+      "headers": { "Authorization": "Bearer YOUR_KEY" }
+    }
+  }
+}
+```
+
+Tools exposed:
+
+| Tool | Purpose |
+|---|---|
+| `generate_context(source, ref, llm=False)` | Build a UCP from a GitHub issue (`owner/repo#123`) or Jira ticket (`PROJ-123`) |
+| `list_contexts()` | List cached packages: id, entity, title, freshness |
+| `get_context(id)` | Full UCP JSON for a cached package |
+| `get_context_markdown(id, token_budget?)` | Canonical Markdown rendering (SPEC §7), optionally truncated by salience |
+
+## REST API
+
+| Method & path | Purpose |
+|---|---|
+| `POST /v1/generate` | Generate a package. Body: `{"source": "github"\|"jira", "ref": "...", "llm": false, "since": null, "audience": null}`. Returns the UCP JSON; headers `X-UCP-Package-Id` and `X-UCP-Cache: hit\|miss`. |
+| `GET /v1/packages` | Cached packages: id, title, entity, generated_at |
+| `GET /v1/packages/{id}` | Full UCP JSON |
+| `GET /v1/packages/{id}/markdown?token_budget=1500` | Canonical Markdown rendering |
+| `GET /healthz`, `GET /readyz` | Liveness / readiness probes (never authenticated) |
+| `GET /docs`, `GET /openapi.json` | OpenAPI documentation |
+
+Errors are RFC 9457 problem documents (`application/problem+json`):
+
+```json
+{"type": "https://ucpcore.org/problems/invalid-ref", "title": "Invalid Reference",
+ "status": 400, "detail": "invalid GitHub reference 'x': expected owner/repo#number..."}
+```
+
+Examples:
+
+```bash
+# Jira (needs JIRA_* env on the server)
+curl -s -X POST http://localhost:8080/v1/generate \
+  -H 'Content-Type: application/json' \
+  -d '{"source": "jira", "ref": "PROJ-123"}'
+
+# LLM-enhanced (needs UCP_LLM_* env on the server)
+curl -s -X POST http://localhost:8080/v1/generate \
+  -H 'Content-Type: application/json' \
+  -d '{"source": "github", "ref": "microsoft/vscode#519", "llm": true}'
+
+# Rendered Markdown under a token budget
+curl -s "http://localhost:8080/v1/packages/github-pallets-flask-5961/markdown?token_budget=1500"
+```
+
+## Configuration
+
+Everything is optional; the server starts with zero configuration and
+reports clearly when a credential is missing for a requested source.
+
+| Variable | Default | Purpose |
+|---|---|---|
+| `UCP_SERVER_HOST` | `127.0.0.1` (Docker image: `0.0.0.0`) | Bind address |
+| `UCP_SERVER_PORT` | `8080` | Bind port |
+| `UCP_SERVER_API_KEY` | *(unset — auth disabled)* | When set, all endpoints except health probes require `Authorization: Bearer <key>` |
+| `UCP_CACHE_DIR` | `~/.cache/ucp-server` | Disk cache for generated packages |
+| `UCP_CACHE_TTL` | `900` (15 min) | Cache TTL in seconds; `0` disables caching |
+| `GITHUB_TOKEN` / `GH_TOKEN` | *(unset)* | GitHub token (public issues work without it, at a low rate limit) |
+| `JIRA_BASE_URL` | *(unset)* | e.g. `https://yourcompany.atlassian.net` |
+| `JIRA_EMAIL` | *(unset)* | Jira Cloud email (Basic auth); omit for Server/DC PAT |
+| `JIRA_API_TOKEN` | *(unset)* | Jira API token or PAT |
+| `UCP_LLM_BASE_URL` | `https://api.openai.com/v1` | OpenAI-compatible endpoint for `llm: true` |
+| `UCP_LLM_API_KEY` | *(unset)* | LLM API key (falls back to `OPENAI_API_KEY`) |
+| `UCP_LLM_MODEL` | `gpt-4o-mini` | LLM model name |
+| `UCP_LOG_JSON` | `false` | `1`/`true` switches to JSON-lines logs |
+| `UCP_LOG_LEVEL` | `INFO` | Log level |
+
+## Security
+
+- **Set `UCP_SERVER_API_KEY` for any non-localhost deployment.** Without it
+  anyone who can reach the port can spend your GitHub/Jira/LLM quota. The
+  key is compared in constant time; health probes stay open for orchestrators.
+- **Bind is `127.0.0.1` by default** when run directly. The Docker image
+  sets `UCP_SERVER_HOST=0.0.0.0` deliberately — the container boundary is
+  the isolation there; publish the port consciously (`-p 127.0.0.1:8080:8080`
+  keeps it local).
+- **No client-supplied URLs.** Clients pass references (`owner/repo#123`,
+  `PROJ-123`) to the two predefined connectors; the server never fetches an
+  arbitrary URL on a client's behalf (no SSRF surface).
+- Request bodies are limited to 64 KiB and validated strictly (unknown
+  fields rejected). Tokens are masked in logs. The Docker image runs as a
+  non-root user.
+
+## Development
+
+```bash
+python3 -m venv .venv && . .venv/bin/activate
+pip install -e ".[dev]"
+pytest
+```
+
+Docker image:
+
+```bash
+docker build -t ucp-server .
+docker run --rm -p 8080:8080 ucp-server
+```

ucpcore_server-0.1.0/pyproject.toml

@@ -0,0 +1,41 @@
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[project]
+name = "ucpcore-server"
+version = "0.1.0"
+description = "Self-hosted UCP server: generate Universal Context Packages from GitHub/Jira over REST and MCP (Streamable HTTP). One command to run."
+readme = "README.md"
+license = "Apache-2.0"
+requires-python = ">=3.11"
+authors = [{ name = "UCP contributors" }]
+keywords = ["ucp", "mcp", "llm", "context", "context-engineering", "server"]
+dependencies = [
+  "pyucp>=0.1.0",
+  "ucp-gen>=0.3.0",
+  "fastapi>=0.115",
+  "uvicorn>=0.30",
+  "fastmcp>=2.3",
+  "pydantic>=2.7",
+  "pydantic-settings>=2.4",
+  "httpx>=0.27",
+]
+
+[project.urls]
+Specification = "https://github.com/ucpcore/ucp"
+Homepage = "https://ucpcore.org"
+
+[project.scripts]
+ucp-server = "ucp_server.__main__:main"
+ucpcore-server = "ucp_server.__main__:main"
+
+[project.optional-dependencies]
+dev = ["pytest>=8", "pytest-asyncio>=0.23"]
+
+[tool.hatch.build.targets.wheel]
+packages = ["src/ucp_server"]
+
+[tool.pytest.ini_options]
+testpaths = ["tests"]
+asyncio_mode = "auto"

ucpcore_server-0.1.0/src/ucp_server/__init__.py

@@ -0,0 +1,4 @@
+"""ucp-server — self-hosted UCP generation service (REST + MCP)."""
+__version__ = "0.1.0"
+
+__all__ = ["__version__"]

ucpcore_server-0.1.0/src/ucp_server/__main__.py

@@ -0,0 +1,52 @@
+"""Entry point: ``ucp-server`` (or ``python -m ucp_server``).
+
+All configuration comes from the environment; see README for the full table.
+Uvicorn handles SIGINT/SIGTERM for a graceful shutdown.
+"""
+from __future__ import annotations
+
+import logging
+import sys
+
+from .config import ConfigError, load_settings
+from .logging_setup import configure_logging
+
+
+def main() -> int:
+    try:
+        settings = load_settings()
+    except ConfigError as exc:
+        print(f"ucp-server: {exc}", file=sys.stderr)
+        return 2
+
+    configure_logging(json_logs=settings.log_json, level=settings.log_level)
+    logger = logging.getLogger("ucp_server")
+    logger.info("ucp-server starting on %s:%s", settings.host, settings.port)
+    if settings.api_key:
+        logger.info("authentication: enabled (Bearer)")
+    else:
+        logger.warning(
+            "authentication: DISABLED — set UCP_SERVER_API_KEY before exposing "
+            "this server beyond localhost"
+        )
+    if settings.cache_ttl > 0:
+        logger.info("cache: %s (ttl %ss)", settings.cache_dir, settings.cache_ttl)
+    else:
+        logger.info("cache: disabled (UCP_CACHE_TTL=0)")
+
+    import uvicorn
+
+    from .app import create_app
+
+    uvicorn.run(
+        create_app(settings),
+        host=settings.host,
+        port=settings.port,
+        log_config=None,  # keep our logging configuration
+        timeout_graceful_shutdown=10,
+    )
+    return 0
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())