# AStockEvent — MCP server for Chinese A-share regulatory filings

[![License: MIT](https://img.shields.io/badge/License-MIT-green.svg)](https://opensource.org/licenses/MIT)
[![MCP](https://img.shields.io/badge/MCP-Model%20Context%20Protocol-blue)](https://modelcontextprotocol.io/)

**Current state folded from A-share filings — not a raw event dump.**

An event feed tells you a plan was announced in June and amended in August. You still
have to work out what is true today. This server does that fold for you: who is still
selling down, which penalty cases are open, which inquiry letters are unanswered.

Every value links back to the source PDF published by the exchange, so you can check us.

---

## Connect

This is a **remote MCP server** (Streamable HTTP). There is nothing to install —
point your MCP client at the URL:

```
https://astockevent.com/mcp/
```

No API key, no sign-up. Rate limits apply and the response tells you when you hit one.

<details>
<summary>Example for clients with a URL-based mcpServers configuration</summary>

```json
{
  "mcpServers": {
    "astockevent": {
      "url": "https://astockevent.com/mcp/"
    }
  }
}
```
</details>

Prefer HTTP? The same data is available over REST — see
**[astockevent.com/docs](https://astockevent.com/docs)**, with the machine-readable
contract at [`/openapi.json`](https://astockevent.com/openapi.json).

---

## Tools

| Tool | What it answers |
|---|---|
| `list_coverage` | What is in scope and what the limits are. Call this before concluding data is missing. |
| `list_company_filings` | Filings held for one company, with source links and any extracted events; up to 50 per call, without list pagination. |
| `get_filing_parsed` | Available parsed text and tables for one recent filing; long documents may be partial. |
| `get_related_filings` | Collected filings of the same company matched by explicit document references. |
| `get_entity_state` | Folded company state, or linked companies for a confirmed actor identifier. |
| `get_event_with_context` | One event plus its whole timeline, in a single call. |
| `whats_new` | Events updated within seven days and linked to filings from the last seven Beijing calendar days, cursor-paged. |
| `scan_recent_events` | Cross-company discovery by filing type within the last seven Beijing calendar days. |

Discovery includes today and uses filing dates, not the age of the case. A new filing can mention an old case. `matched_filing` identifies the qualifying filing and its source; root event fields describe current context. Empty windows stay empty. Scan returns effective dates, a matched count and truncation flag, with at most 100 events per page. Continue with `cursor` until it is null; `truncated` may still be true on the last page because it compares the total with that page’s size. Omit dates/phase on continuation or repeat the effective values; changing filters requires a fresh query. Expired windows are errors, never a way into history. Results can change between pages; restart polling from the first page and deduplicate by event id. Known company/entity/event queries retain their existing historical context.

Parsed text is available for filings dated at most seven Beijing calendar days ago
(eight dates including today), in chunks of up to 50,000 characters. Source documents
may be only partly parsed: reaching the last stored chunk does not mean the full PDF
was parsed. Use the source PDF whenever you need the complete original.

## Coverage

**Four structured event types**, with broader company-filing and source-document access.
The coverage endpoint states the current scope and limits.

| Type | Folded into |
|---|---|
| Share reduction by major shareholders | The plan that is still live, and how much of its cap is used up |
| Administrative penalty proceedings | Each case grouped by case number, folded to its current stage |
| Exchange inquiry letters | Received / replied / overdue — the state of the conversation |
| Ordinary A-share trading halts and resumptions | Individual halt cycles, reasons and dates, available through event details and recent discovery |

Company folded state covers reductions, penalties and regulatory letters. Stock halt
cycles are available through filings, event details and scans; they are not folded
into company state. Convertible-bond and preferred-share halts are outside this scope.

Call `list_coverage` for the authoritative, always-current answer.

---

## Two things worth knowing

**Empty is not the same as unknown.** A company with no filings of a type comes back
as *covered, nothing found* — not as an empty result. A security we do not carry comes
back as *not found*, with a reason. Telling those two apart is the point of this service.

**We report, we do not judge.** Objective extractions only: no ratings, no scores, no
attribution of price moves. What you build on top of the facts is yours.

---

## Status

Pre-release. Coverage is narrow and stated honestly; the API may change.
If you are using it and something is missing or wrong, we want to hear it —
[tell us here](https://astockevent.com/feedback) or email `contact@astockevent.com`.

## About this repository

This repo is the **public front door**: what the server is, how to connect, and the
[`server.json`](./server.json) descriptor for the MCP registry.

The server itself is *remote* — you point a client at a URL rather than installing code —
so there is no server implementation to publish here. Extraction engines, crawlers and
schemas live in a private repository.

## License

MIT — see [LICENSE](./LICENSE).