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
• Python 3.11, installed automatically by uv if necessary
• On developer PCs: built-in Windows PowerShell 5.1 or newer

Start the shared server

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:

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:

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

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

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.