Metadata-Version: 2.4
Name: lastseen-mcp
Version: 0.1.0
Summary: MCP server: check whether an npm package / GitHub Action / MCP server / Docker image is dead or abandoned — dated observations from lastseen.dev, free, no key
Author: lastseen.dev
License: MIT
Project-URL: Homepage, https://lastseen.dev
Project-URL: Documentation, https://lastseen.dev/api/v1/docs
Keywords: mcp,model-context-protocol,supply-chain,mortality,abandonment,npm,github-actions,sbom
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: MIT License
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.10
Classifier: Topic :: Software Development :: Quality Assurance
Requires-Python: >=3.10
Description-Content-Type: text/markdown
License-File: LICENSE
Dynamic: license-file

# lastseen-mcp

**Is this dependency dead?** An MCP server that answers whether an npm package, GitHub
Action, MCP server or Docker image is **dead or abandoned** — from **dated observations**
published by [lastseen.dev](https://lastseen.dev). Free, no API key, zero telemetry.

- **Lookups, not advice.** Every answer is a dated observation with its source. The server
  never says "use X instead", never scores, never ranks by preference, never asserts urgency.
- **Fails closed.** An unknown or fabricated subject returns a clean `not_observed` — never a
  fabricated result. A network/store error *degrades* (try later); it is never read as "dead".
- **Absence ≠ gone.** Not having a record means "not checked", never "deleted". Only an
  authoritative HTTP 404 is a deletion.
- **Pure standard library.** No `mcp` package, no `requests`, no FastAPI/Starlette — nothing
  that can conflict with a host app. It speaks JSON-RPC 2.0 over stdio and calls the
  lastseen.dev free HTTP API over `urllib`.

## Install

```bash
pipx install lastseen-mcp
# or run without installing:
uvx lastseen-mcp
```

Requires Python ≥ 3.10. No dependencies.

## Use it in an MCP client

Add to your client's MCP server config (Claude Desktop / Cursor style):

```json
{
  "mcpServers": {
    "lastseen": {
      "command": "lastseen-mcp"
    }
  }
}
```

(If you installed with `uvx`, use `"command": "uvx", "args": ["lastseen-mcp"]`.)

## Tools

| Tool | What it does |
| --- | --- |
| `check_entity(slug, live?)` | Dated survival observation series for one `owner/repo` (e.g. `actions/checkout`). Optional `live=true` attaches a live GitHub read (absence ≠ gone). |
| `check_org(name)` | Dated survival states for every held component under a GitHub owner/org (e.g. `actions`). |
| `check_manifest(paste)` | Paste a GitHub Actions workflow (`uses:` refs) or a list of `owner/repo` lines; get the dated state per component. Components not held are reported `not_observed`. |
| `survival_profile(category)` | Category ranking. **Not available over the free HTTP API** — returns an honest not-supported result pointing to the per-entity/org/manifest lookups and the CC-BY dumps. See *Limitations*. |

### States

`alive` (≤180d since last commit) · `dormant` (180–365d) · `abandoned` (>365d) ·
`archived` (repo archived) · `deleted` (authoritative HTTP 404) · `eol` (declared
end-of-life) · `unknown-stale` (the observation the verdict rests on is older than the 180-day
threshold and was not re-verified — no state is asserted; **not** a death) · `not_observed`
(403 / 429 / timeout / not held — **not** dead).

The freshness gate that produces `unknown-stale` is applied server-side by lastseen.dev; this
client passes the gated `latest_state` and `staleness` through verbatim.

## Privacy

Zero telemetry. This client stores nothing and transmits no identifier about you, your org,
or the subjects you look up. It only issues anonymous GET requests to the public API.

## Limitations

`survival_profile` (category-level ranking) has **no** corresponding endpoint on the free
HTTP API, so it returns a factual not-supported result rather than fabricating a ranking. The
tool is retained in the schema for parity. Bulk category data is published as the CC-BY dumps
on [lastseen.dev](https://lastseen.dev). The per-entity, per-org and per-manifest lookups are
fully supported.

`check_manifest` looks up at most 30 parsed components per call (latency and free-tier rate
bound); any remainder is reported as `n_truncated`.

## Licensing

- **Code:** MIT (see `LICENSE`).
- **Data:** the mortality/survival observations returned by the API are published by
  lastseen.dev under **CC-BY-4.0** (attribution required). The two licenses are independent.

## Links

- Service & data: <https://lastseen.dev>
- API docs (self-describing JSON): <https://lastseen.dev/api/v1/docs>
