# Company Skills Gateway

This is a deliberately small MCP server for a small engineering team. It does two things:

1. Reads team `SKILL.md` files from a folder and returns the relevant ones to Cursor.
2. Records who requested guidance and which skill versions were returned in a local SQLite file.

There is no PostgreSQL, Alembic, ORM, Docker requirement, OIDC provider, webhook, polling loop,
scheduled updater, metrics stack, admin framework, or signed client release pipeline.

## How it works

- Put each skill at `sample-skill-catalog/<skill-name>/SKILL.md`.
- Cursor calls `company-skills.prepare_context` over Streamable HTTP.
- The server reads the files on that request, so saved edits are live immediately.
- A deterministic matcher uses repository, path, language, framework, task kind, and keywords.
- One row is written to `company-skills.db` with the developer, repository, result, and exact
  skill names, versions, and hashes.

The server does **not** store task summaries, source code, branches, paths, secrets, or environment
values. A delivery log proves that guidance was returned, not that Cursor followed it.

## Requirements

- [uv](https://docs.astral.sh/uv/)
- Python 3.11, installed automatically by uv if necessary
- On developer PCs: built-in Windows PowerShell 5.1 or newer

## Start the shared server

```bash
uv sync --frozen
cp .env.example .env.dev
ln -sf .env.dev .env
uv run --env-file .env company-skills-gateway
```

The defaults listen only on `127.0.0.1:8000`. Set `SKILLS_HOST=0.0.0.0` on the one machine that
will serve the six developers, then use that machine's internal DNS name in the installer.

Check it:

```bash
curl http://127.0.0.1:8000/healthz
curl http://127.0.0.1:8000/usage
```

If `SKILLS_API_KEY` is set, `/mcp` and `/usage` require it:

```bash
curl -H "X-Skills-Key: your-shared-key" http://127.0.0.1:8000/usage
```

Treat this as a simple internal shared key, not a replacement for network access controls. Put the
server on the company LAN/VPN and use HTTPS through the reverse proxy you already have if traffic
leaves a trusted network.

## Install on Windows

From a clone or shared copy of this repository:

```powershell
powershell -ExecutionPolicy Bypass -File .\installer\Install-CompanySkills.ps1 `
  -McpUrl 'http://skills-box:8000/mcp' `
  -ApiKey 'your-shared-key'
```

Omit `-ApiKey` if the server does not set `SKILLS_API_KEY`. The installer uses `$env:USERNAME` for
usage attribution; override it with `-Developer`. It only:

- merges a `company-skills` entry into `~/.cursor/mcp.json`, including the developer header; and
- copies the small bootstrap skill to `~/.agents/skills/company-skills-bootstrap/SKILL.md`.

It does not require administrator rights, PowerShell modules, code-signing certificates, scheduled
tasks, workspace scanning, or a separate update process. Server-side skill changes need no client
update. Restart Cursor once after installation.

To remove those two entries:

```powershell
powershell -ExecutionPolicy Bypass -File .\installer\Uninstall-CompanySkills.ps1
```

## Add or change a skill

Copy one of the existing folders and edit its `SKILL.md`. The useful matching fields are:

```yaml
---
name: example-skill
description: When this team guidance is useful.
paths: ["**/*.py"]
metadata:
  version: "1.0.0"
  status: active
  languages: [python]
  frameworks: [fastapi]
  repo_patterns: ["engineering/*"]
  task_kinds: [implementation, review]
  trigger_keywords: [api, endpoint]
  priority: 50
  always_include: false
---
```

Then validate the whole directory:

```bash
uv run company-skills-catalog sample-skill-catalog
```

Unknown metadata is ignored on purpose, which makes experiments cheap. A malformed skill name,
frontmatter block, or body makes `/healthz` fail visibly instead of silently serving stale content.

## Running

| Command | What it does |
|---|---|
| `uv run --env-file .env company-skills-gateway` | Runs the MCP service and usage endpoint. |
| `uv run company-skills-catalog sample-skill-catalog` | Validates and lists the current skills. |
| `uv run pytest --cov` | Runs all tests and the coverage ratchet. |
| `uv run ruff check .` | Runs lint checks. |
| `uv run basedpyright` | Runs type checks. |

## Code map

- `config.py` — seven environment-backed settings.
- `catalog.py` — skill parsing and deterministic matching.
- `usage.py` — one SQLite table and one report.
- `main.py` — the MCP tool, three HTTP routes, and optional shared-key check.
- `installer/` — one install script and one uninstall script.

SQLite is intentionally the operational interface too. If you want an ad hoc report, use the
`/usage` JSON or open `company-skills.db` with any SQLite browser. If the team eventually outgrows
one process and one disk, that is the point to reconsider a shared database—not before.