bca-mcp 0.2.3__tar.gz

bca_mcp-0.2.3/.gitignore

@@ -0,0 +1,54 @@
+# Python
+__pycache__/
+*.py[cod]
+*$py.class
+*.so
+.Python
+build/
+develop-eggs/
+dist/
+downloads/
+eggs/
+.eggs/
+lib/
+lib64/
+parts/
+sdist/
+var/
+wheels/
+share/python-wheels/
+*.egg-info/
+.installed.cfg
+*.egg
+MANIFEST
+
+# Virtual envs
+.venv/
+venv/
+ENV/
+env/
+
+# Test / coverage
+.pytest_cache/
+.coverage
+.coverage.*
+htmlcov/
+.tox/
+.nox/
+coverage.xml
+*.cover
+
+# IDE
+.vscode/
+.idea/
+*.swp
+*.swo
+.DS_Store
+
+# Env
+.env
+.env.local
+.env.*.local
+
+# Build artifacts
+*.whl

bca_mcp-0.2.3/CHANGELOG.md

@@ -0,0 +1,41 @@
+# Changelog
+
+All notable changes to `bca-mcp` are documented here.
+
+This project follows [Semantic Versioning](https://semver.org/) and [Keep a Changelog](https://keepachangelog.com/en/1.1.0/).
+
+## [0.2.0] — 2026-04-21
+
+### Added
+- **`bca` CLI** bundled with the package — a Typer + Rich terminal UI over the same REST API the MCP server wraps. Registered as a console script (`pip install bca-mcp` gives you both `bca-mcp` and `bca`).
+  - `bca login` — stores API key in `~/.bca/config.toml` (chmod 600).
+  - `bca config show` — inspect config file location + masked key.
+  - `bca news search <query>` — rich table of articles with `cite_url`.
+  - `bca entity <slug>` — entity dossier panel.
+  - `bca price <tickers>` — spot + 24h change table.
+  - `bca market overview` — top-N by market cap.
+  - `bca indicator <name> <entity> --window {7d,30d,90d}` — proprietary indicator reads.
+  - `bca explainer <slug>` — academy lesson rendered as markdown.
+  - `bca agent <skill>` — kicks off async agent-backed jobs and polls to completion.
+  - `bca version` — shows CLI + live API version.
+  - Every command accepts `--json` for pipe-friendly output.
+- `BCA_API_BASE` is now the primary base-URL env var; `BCA_API_BASE_URL` is accepted as a legacy alias (matches the TypeScript sibling + `server.json` contract).
+
+### Changed
+- User-Agent bumped to `bca-mcp/0.2.0`.
+
+## [0.1.0] — 2026-04-21
+
+### Added
+- Initial Python release with stdio transport — v0.1 scaffold, **8 read-only tools** (minimum viable parity with `@blockchainacademics/mcp` TS v0.1).
+- **Content & corpus (6):** `search_news`, `get_article`, `get_entity`, `list_entity_mentions`, `list_topics`, `get_explainer`.
+- **Market (2):** `get_price`, `get_market_overview`.
+- Typed async HTTPS client (`httpx.AsyncClient`) with `BCA_API_KEY` header injection, 20s default timeout, and both `request()` (GET) and `post()` methods.
+- Fail-fast at server construction if `BCA_API_KEY` is not set — misconfigured MCP hosts surface the error at startup, not on first tool call.
+- Envelope passthrough for `status=integration_pending` / `status=upstream_error` bodies (pass as successful tool responses; MCP client decides how to surface).
+- Structured error taxonomy (`BCA_AUTH`, `BCA_RATE_LIMIT`, `BCA_UPSTREAM`, `BCA_NETWORK`, `BCA_BAD_REQUEST`) mirroring the TypeScript sibling.
+- Attribution surfacing (`cite_url`, `as_of`, `source_hash`) on every tool response; `null` preserved when upstream omits.
+- Smoke test suite using `pytest` + `pytest-httpx` — schema + transport validation with no live API calls.
+- LangChain integration via `langchain-mcp-adapters` in `examples/langchain_agent.py`.
+- Eliza integration notes in `examples/eliza_plugin.md`.
+- Sibling of the TypeScript `@blockchainacademics/mcp` package. v0.2 will expand the tool surface toward the 99-tool TS parity target.

bca_mcp-0.2.3/HANDOFF.md

@@ -0,0 +1,76 @@
+# bca-mcp-python — Handoff
+
+**Status (2026-04-21):** 0.1.0 built, tested, committed locally. Ready to push to GitHub + publish to PyPI.
+
+## What exists
+
+- `src/bca_mcp/` — 8-tool MVP for LangChain / generic-Python-agent parity with `@blockchainacademics/mcp@0.2.2`
+  - Tools: `search_news`, `get_article`, `get_entity`, `list_entity_mentions`, `list_topics`, `get_explainer`, `get_price`, `get_market_overview`
+  - Envelope-aware client at `client.py` (parses `{data, cite_url, as_of, source_hash}` and returns the unwrapped payload with attribution fields passed through)
+  - stdio transport only (HTTP/SSE is v0.2+)
+- `tests/` — 23 tests, all green (`pytest`)
+- `dist/bca_mcp-0.1.0{.tar.gz,-py3-none-any.whl}` — built, `twine check` PASSED
+- Git: initialized on `main`, first commit landed (no remote yet)
+
+## Publish steps (Wael)
+
+```bash
+cd ~/bca-mcp-python
+
+# 1. Create GitHub repo + push
+gh repo create blockchainacademics/bca-mcp-python --public --source=. --remote=origin --push
+
+# 2. Create PyPI API token at https://pypi.org/manage/account/token/
+#    Scope: project-specific once uploaded; first upload needs account-wide token
+#    Save as: ~/.pypirc   OR   export TWINE_USERNAME=__token__ TWINE_PASSWORD=pypi-...
+
+# 3. Upload
+source .venv/bin/activate
+twine upload dist/*
+
+# 4. Tag release
+git tag v0.1.0
+git push origin v0.1.0
+gh release create v0.1.0 --title "0.1.0 — 8-tool MVP" --notes-file CHANGELOG.md
+```
+
+## Smoke test post-publish
+
+```bash
+pipx run bca-mcp --help       # should print stdio banner
+# OR in a LangChain agent:
+pip install bca-mcp
+```
+
+Config snippet for Claude Desktop (for parity testing vs TS package):
+
+```json
+{
+  "mcpServers": {
+    "bca": {
+      "command": "pipx",
+      "args": ["run", "bca-mcp"],
+      "env": {"BCA_API_KEY": "bca_live_..."}
+    }
+  }
+}
+```
+
+## Parity status vs TypeScript package
+
+8/99 tools shipped. The Python package is the **LangChain / Eliza-Python entry point**, not a mirror of the full TS surface. v0.2 will expand once the TS v0.2.0 is listed in the Anthropic directory and we know which tools agents actually call.
+
+## Known gaps (v0.2 targets)
+
+- HTTP/SSE transport for hosted MCP (Virtuals, Bedrock)
+- Remaining 91 tools (market data deep cuts, on-chain, indicators, agent-backed jobs)
+- Example notebook (`examples/langchain_agent.ipynb`) — scaffold exists, needs a live run + output commit
+
+## Local dev
+
+```bash
+cd ~/bca-mcp-python
+source .venv/bin/activate   # Python 3.14.4
+pytest                      # 23 tests, <1s
+python -m bca_mcp           # runs stdio server against localhost:8000 unless BCA_API_BASE set
+```

bca_mcp-0.2.3/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Blockchain Academics
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

bca_mcp-0.2.3/PKG-INFO

@@ -0,0 +1,236 @@
+Metadata-Version: 2.4
+Name: bca-mcp
+Version: 0.2.3
+Summary: Blockchain Academics MCP server + `bca` CLI — crypto news, entity dossiers, market data, proprietary indicators, and academy explainers for AI agents
+Project-URL: Homepage, https://blockchainacademics.com
+Project-URL: Repository, https://github.com/blockchainacademics/bca-mcp-python
+Project-URL: Issues, https://github.com/blockchainacademics/bca-mcp-python/issues
+Author-email: Blockchain Academics <dev@blockchainacademics.com>
+License-Expression: MIT
+License-File: LICENSE
+Keywords: agents,ai,blockchain,crypto,llm,mcp,news
+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: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Topic :: Software Development :: Libraries :: Python Modules
+Requires-Python: >=3.10
+Requires-Dist: httpx>=0.27.0
+Requires-Dist: mcp>=1.0.0
+Requires-Dist: pydantic>=2.7.0
+Requires-Dist: rich>=13.7
+Requires-Dist: tomli-w>=1.0
+Requires-Dist: tomli>=2.0; python_version < '3.11'
+Requires-Dist: typer>=0.12
+Provides-Extra: dev
+Requires-Dist: build>=1.2; extra == 'dev'
+Requires-Dist: pytest-asyncio>=0.23; extra == 'dev'
+Requires-Dist: pytest-httpx>=0.30; extra == 'dev'
+Requires-Dist: pytest>=8.0; extra == 'dev'
+Requires-Dist: respx>=0.21; extra == 'dev'
+Description-Content-Type: text/markdown
+
+# bca-mcp
+
+The canonical crypto MCP server for AI agents — **Python edition**. 3,500+ editorial articles, 200+ entity dossiers, 43 academy lessons, and live market data — accessible as MCP tools your agent can call natively.
+
+Sibling of [`@blockchainacademics/mcp`](https://www.npmjs.com/package/@blockchainacademics/mcp) (TypeScript). Same REST API. Same attribution contract. Use whichever fits your stack.
+
+**v0.2.0 ships 8 read-only MCP tools + the `bca` CLI** — the most-used corpus + market endpoints, plus a terminal-first way to explore them. Later versions expand toward parity with the TS sibling (99 tools). Starting narrow on the MCP surface is deliberate: tight tools, sharp descriptions, low-risk publish.
+
+## Why
+
+LLMs hallucinate about crypto. BCA ships ground-truth editorial content with full attribution. Plug this MCP server into Claude Desktop, LangChain, LlamaIndex, Eliza, or any MCP-compatible agent and your model queries the BCA corpus like any other tool — with `cite_url`, `as_of`, and `source_hash` on every response.
+
+## Install
+
+```bash
+pip install bca-mcp
+# or, isolated:
+pipx install bca-mcp
+```
+
+## Configure
+
+Get an API key at **https://brain.blockchainacademics.com/pricing** (free tier: 1,000 calls/month; paid tiers unlock expanded rate limits and — in later versions — agent-backed research generation).
+
+Set the env var before launching the server:
+
+```bash
+export BCA_API_KEY="bca_live_xxxxxxxxxxxxxxxx"
+# optional: override the default https://api.blockchainacademics.com
+export BCA_API_BASE="https://api.blockchainacademics.com"
+# BCA_API_BASE_URL is also accepted as a legacy alias
+```
+
+> The server **fails fast at startup** if `BCA_API_KEY` is missing. Misconfigured hosts surface the problem immediately instead of on the first tool call.
+
+## Use from Claude Desktop
+
+Add to `claude_desktop_config.json` (macOS: `~/Library/Application Support/Claude/claude_desktop_config.json`):
+
+```json
+{
+  "mcpServers": {
+    "blockchainacademics": {
+      "command": "python",
+      "args": ["-m", "bca_mcp"],
+      "env": { "BCA_API_KEY": "bca_live_xxxxxxxxxxxxxxxx" }
+    }
+  }
+}
+```
+
+Restart Claude Desktop — the 8 tools appear in the tool picker. If you installed via `pipx`, you can swap `"command": "bca-mcp"` with empty `args` (a console-script entry point is registered by the package).
+
+## Use from LangChain
+
+Ten lines via [`langchain-mcp-adapters`](https://github.com/langchain-ai/langchain-mcp-adapters):
+
+```python
+import asyncio, os, sys
+from mcp import ClientSession, StdioServerParameters
+from mcp.client.stdio import stdio_client
+from langchain_mcp_adapters.tools import load_mcp_tools
+
+async def main():
+    params = StdioServerParameters(
+        command=sys.executable, args=["-m", "bca_mcp"],
+        env={**os.environ, "BCA_API_KEY": os.environ["BCA_API_KEY"]},
+    )
+    async with stdio_client(params) as (r, w), ClientSession(r, w) as s:
+        await s.initialize()
+        tools = await load_mcp_tools(s)   # -> list[StructuredTool]
+        print(await tools[0].ainvoke({"query": "stablecoin regulation"}))
+
+asyncio.run(main())
+```
+
+Full worked example in [`examples/langchain_agent.py`](./examples/langchain_agent.py). Raw MCP client loop (no LangChain) in [`examples/generic_agent.py`](./examples/generic_agent.py).
+
+## Use from Eliza
+
+See [`examples/eliza_plugin.md`](./examples/eliza_plugin.md) for integration notes — `bca-mcp` plugs into Eliza's MCP plugin surface as a stdio-transport server.
+
+## The `bca` CLI
+
+`pip install bca-mcp` also registers a terminal-first CLI. It talks to the same REST API as the MCP server — handy for debugging, quick lookups, and shell pipelines.
+
+```bash
+bca login                                # store API key in ~/.bca/config.toml (chmod 600)
+bca news search "bitcoin etf" -n 5       # recent articles, rich table + cite_url
+bca entity ethereum                      # dossier panel
+bca price BTC,ETH,SOL                    # spot + 24h change table
+bca market overview -n 10                # top-N by market cap
+bca indicator coverage-index bitcoin -w 30d
+bca explainer what-is-a-blockchain       # rendered markdown
+bca agent summarize-whitepaper --url https://ethereum.org/…
+bca version                              # CLI + live API version
+```
+
+Every command accepts `--json` for unformatted output suitable for `jq` pipelines. Env vars (`BCA_API_KEY`, `BCA_API_BASE`) take precedence over `~/.bca/config.toml`.
+
+## Tool catalog (v0.1.0 — 8 tools)
+
+| Tool | Category | Endpoint | Tier |
+|---|---|---|---|
+| `search_news` | content | `GET /v1/articles/search` | Starter |
+| `get_article` | content | `GET /v1/articles/{slug}` | Starter |
+| `get_entity` | content | `GET /v1/entities/{slug}` | Starter |
+| `list_entity_mentions` | content | `GET /v1/entities/{slug}/mentions` | Starter |
+| `list_topics` | content | `GET /v1/topics` | Starter |
+| `get_explainer` | content | `GET /v1/academy/{slug}` | Starter |
+| `get_price` | market | `GET /v1/market/price` | Starter |
+| `get_market_overview` | market | `GET /v1/market/overview` | Starter |
+
+All v0.1 tools are **free tier** — no paid plan required to call them.
+
+### Tool details
+
+#### `search_news`
+Required: `query` (1–512 chars). Optional: `entity`, `since` (ISO 8601), `topic`, `limit` (1–50, default 10).
+
+#### `get_article`
+Required: `slug` (1–240 chars).
+
+#### `get_entity`
+Required: **exactly one** of `slug` (e.g. `"vitalik-buterin"`) or `ticker` (e.g. `"ETH"`, case-insensitive). Aliases resolve automatically (`CZ` → `changpeng-zhao`, `Maker` → `makerdao`, `BSC` → `bnb-chain`, …).
+
+#### `list_entity_mentions`
+Required: `slug` (entity). Optional: `since` (ISO 8601), `limit` (1–200, default 20).
+
+#### `list_topics`
+No arguments.
+
+#### `get_explainer`
+Required: **exactly one** of `slug` (e.g. `"what-is-a-blockchain"`) or `topic` (keyword).
+
+#### `get_price`
+Required: `ids` (comma-separated CoinGecko IDs, e.g. `"bitcoin,ethereum"` — NOT exchange tickers). Optional: `vs` (quote currency, default `usd`).
+
+#### `get_market_overview`
+Optional: `limit` (1–100, default 20).
+
+## Attribution contract
+
+Every response includes a structured `attribution` block:
+
+```json
+{
+  "data": { ... },
+  "attribution": {
+    "cite_url": "https://blockchainacademics.com/...",
+    "as_of": "2026-04-19T12:34:56Z",
+    "source_hash": "sha256:..."
+  },
+  "meta": null
+}
+```
+
+**When your agent surfaces BCA content to a user, you MUST link `cite_url`.** This is the core trade: BCA gives agents ground-truth citations; agents give BCA distribution. `as_of` and `source_hash` let downstream systems detect staleness and verify content integrity. Fields are preserved as `null` (not dropped) when upstream omits them, so agents can detect missing provenance explicitly.
+
+## Degraded-state envelopes
+
+The BCA API sometimes returns `status=integration_pending` or `status=upstream_error` envelopes (200 HTTP) when a specific data source is temporarily unavailable. **The MCP server passes these through as successful tool responses** — your agent sees the envelope and decides how to surface it. This matches the TS sibling's behavior.
+
+## Errors
+
+The server never crashes the stdio process. All failures surface as MCP responses with `isError: true` and a JSON body:
+
+```json
+{ "error": { "code": "BCA_AUTH", "message": "..." } }
+```
+
+| Code | Meaning |
+|---|---|
+| `BCA_AUTH` | Missing/invalid `BCA_API_KEY` (HTTP 401/403) |
+| `BCA_RATE_LIMIT` | Rate limit exceeded (HTTP 429 — honor `Retry-After`) |
+| `BCA_UPSTREAM` | BCA API returned 5xx or malformed JSON |
+| `BCA_NETWORK` | Network failure or 20s timeout exceeded |
+| `BCA_BAD_REQUEST` | Invalid tool arguments or 4xx response |
+
+## Development
+
+```bash
+python -m venv .venv
+source .venv/bin/activate
+pip install -e '.[dev]'
+pytest -q
+```
+
+Run the server directly for debugging:
+
+```bash
+BCA_API_KEY=... python -m bca_mcp
+```
+
+## Contributing
+
+Issues, PRs, and feature requests: https://github.com/blockchainacademics/bca-mcp-python
+
+## License
+
+MIT © 2026 Blockchain Academics

bca_mcp-0.2.3/PORT_MANIFEST.md

@@ -0,0 +1,146 @@
+# BCA MCP Python Port Manifest — Task #122
+
+**Generated:** 2026-04-21
+**Status:** Port planning document (READ-ONLY exploration — no code changes)
+**Source of truth:** `~/bca-mcp-ts/src/index.ts` (99 tools registered via `entry()` calls)
+
+## Tool count
+
+- **TypeScript total:** 99 tools
+- **Python v0.1.0 ported:** 8 tools
+- **Remaining to port:** 91 tools
+
+## Already ported (8)
+
+| Tool | Python module | TS parity |
+|---|---|---|
+| `search_news` | `tools/search_news.py` | ✓ |
+| `get_article` | `tools/content.py` | ✓ |
+| `get_entity` | `tools/get_entity.py` | ✓ |
+| `list_entity_mentions` | `tools/content.py` | ✓ |
+| `list_topics` | `tools/content.py` | ✓ |
+| `get_explainer` | `tools/get_explainer.py` | ✓ |
+| `get_price` | `tools/market.py` | ✓ |
+| `get_market_overview` | `tools/market.py` | ✓ |
+
+No schema drift vs. TS.
+
+## Category breakdown (unported)
+
+| Category | TS count | Ported | Delta |
+|---|---|---|---|
+| News & Entities | 3 | 3 | 0 |
+| Content & Corpus | 4 | 4 | 0 |
+| Market Data | 4 | 2 | **2** |
+| On-Chain | 4 | 0 | **4** |
+| Sentiment | 3 | 0 | **3** |
+| Indicators | 6 | 0 | **6** |
+| Agent Jobs | 6 | 0 | **6** |
+| Directories | 13 | 0 | **13** |
+| Fundamentals | 6 | 0 | **6** |
+| Chain-Specific | 4 | 0 | **4** |
+| Compute/AI | 2 | 0 | **2** |
+| Memes | 4 | 0 | **4** |
+| Microstructure | 5 | 0 | **5** |
+| Narrative | 5 | 0 | **5** |
+| Regulatory | 4 | 0 | **4** |
+| Security | 4 | 0 | **4** |
+| Services (POST) | 3 | 0 | **3** |
+| History/Time-Series | 4 | 0 | **4** |
+| Corpus Meta | 7 | 0 | **7** |
+| Memos/Theses | 4 | 0 | **4** |
+| Social Signals | 2 | 0 | **2** |
+| Currencies | 2 | 0 | **2** |
+| **Total** | **99** | **8** | **91** |
+
+## Unported tools by category
+
+**Market (2):** `get_ohlc`, `get_pair_data`
+
+**On-Chain (4):** `get_wallet_profile`, `get_tx`, `get_token_holders`, `get_defi_protocol`
+
+**Sentiment (3):** `get_sentiment`, `get_social_pulse` (⚠ integration_pending), `get_fear_greed`
+
+**Indicators (6 — all share `entity_slug` + `window` pattern):** `get_coverage_index`, `get_narrative_strength`, `get_sentiment_velocity`, `get_editorial_premium`, `get_kol_influence`, `get_risk_score`
+
+**Agent Jobs (6 — async POST + polling):** `generate_due_diligence`, `generate_tokenomics_model`, `summarize_whitepaper`, `translate_contract`, `monitor_keyword`, `get_agent_job`
+
+**Directories (13):** `list_stablecoins`, `list_nft_communities`, `list_yields`, `list_aggregators`, `list_mcps`, `list_trading_bots`, `list_vcs`, `list_jobs`, `list_smart_contract_templates`, `get_smart_contract_template`, `list_marketing_templates`, `get_marketing_template`, `build_custom_indicator`
+
+**Fundamentals (6):** `get_tokenomics`, `get_audit_reports`, `get_team_info`, `get_roadmap`, `compare_protocols`, `check_rugpull_risk`
+
+**Chain-Specific (4):** `get_solana_ecosystem`, `get_l2_comparison`, `get_bitcoin_l2_status`, `get_ton_ecosystem`
+
+**Compute/AI (2):** `get_compute_pricing`, `get_ai_crypto_metrics`
+
+**Memes (4):** `track_pumpfun`, `track_bonkfun`, `check_memecoin_risk`, `get_degen_leaderboard`
+
+**Microstructure (5):** `get_funding_rates`, `get_options_flow`, `get_liquidation_heatmap`, `get_exchange_flows`, `predict_listing`
+
+**Narrative (5):** `track_narrative`, `get_ai_agent_tokens`, `get_depin_projects`, `get_rwa_tokens`, `get_prediction_markets`
+
+**Regulatory (4):** `get_regulatory_status`, `track_sec_filings`, `get_mica_status`, `get_tax_rules`
+
+**Security (4):** `check_exploit_history`, `check_phishing_domain`, `get_bug_bounty_programs`, `scan_contract`
+
+**Services (3, POST):** `book_kol_campaign`, `request_custom_research`, `submit_listing`
+
+**History (4):** `get_history_prices`, `get_history_sentiment`, `get_history_correlation`, `get_history_coverage`
+
+**Corpus Meta (7):** `list_entities`, `get_topic`, `search_academy`, `get_trending`, `get_unified_feed`, `list_sources`, `get_recent_stories`
+
+**Memos/Theses (4):** `list_memos`, `get_memo`, `list_theses`, `get_thesis`
+
+**Social Signals (2):** `get_social_signals`, `get_social_signals_detail`
+
+**Currencies (2):** `list_currencies`, `get_currency_feed`
+
+## Shared patterns (Python reusable primitives)
+
+- **Window enum:** `Literal['1d', '7d', '30d', '90d']` (or subset). Factor into `types.py`.
+- **Entity slug:** `str` validated by regex `^[a-z0-9]+(?:-[a-z0-9]+)*$`. Shared validator.
+- **Chain enum:** 7 tools share same chain list (eth, solana, arbitrum, base, optimism, polygon, bnb). Factor.
+- **Ticker/symbol:** common across sentiment + microstructure + history.
+- **Async job pattern:** agent-jobs return `{job_id, status_url}`; `get_agent_job` polls. Single base class.
+- **Untrusted-content wrapping:** TS wraps third-party content in `<untrusted_content>` tags — mirror in Python.
+
+## Batched execution plan
+
+| Batch | Tools | LOC est. | Categories | Notes |
+|---|---|---|---|---|
+| 1 | 4 | 150–180 | market, onchain core | Simplest endpoints, high-demand |
+| 2 | 5 | 120–150 | sentiment, social_signals | 1 integration_pending |
+| 3 | 7 | 140–170 | indicators, onchain token_holders | Shared window+slug pattern |
+| 4 | 7 | 160–200 | fundamentals, onchain defi | |
+| 5 | 6 | 180–220 | agent_jobs (async POST + poll) | New pattern class |
+| 6 | 16 | 250–320 | directories, services | Largest batch; all list-shaped |
+| 7 | 15 | 200–250 | narrative, regulatory, security, compute | |
+| 8 | 17 | 180–220 | chain-specific, memes, microstructure, history | |
+| 9 | 13 | 150–180 | corpus_meta, memos_theses, currencies | |
+
+**Total:** 9 batches, 91 tools, ~1,630–1,890 LOC + tests.
+
+## Recommended Batch 1 targets (start here)
+
+1. `get_ohlc` — `GET /v1/market/ohlc` | params: id, days, vs
+2. `get_pair_data` — `GET /v1/market/pair` | params: chain, pair
+3. `get_wallet_profile` — on-chain research foundation
+4. `get_tx` — transaction decoding
+5. `get_token_holders` — concentration risk
+
+Unblocks ~30% of downstream use cases; zero cross-batch dependencies.
+
+## Integration risks (full audit)
+
+- **Only one tool flagged** as `integration_pending`: `get_social_pulse` (Twitter/Reddit OAuth pending). Its Python port is the same shape — backend returns envelope `{data: null, status: "integration_pending"}` unchanged.
+- Schema fidelity across `extended.ts` (31 KB, 812 lines) is consistent — no sketchy zod declarations.
+- No missing implementation details in TS source.
+- `client.py` in Python MCP already supports GET + POST patterns needed.
+
+## Open decisions for Wael before executing batches
+
+1. **Version gate:** `pyproject.toml` currently reads `0.2.0`. Options: (a) roll back to `0.2.0.dev0` and bump to `0.2.0` only when all 91 land, (b) keep `0.2.0` and ship batches as `0.2.0.post1`, `0.2.0.post2`, etc.
+2. **0.1.0 release artifact:** currently un-pushed, un-tagged. Ship `v0.1.0` to PyPI first so we have an 8-tool baseline in the wild? Or go straight to 0.2.0 with 99 tools?
+3. **CLI flag:** `--list-tools` isn't implemented. Add as part of batch 1, or keep `python -m bca_mcp --list-tools` as the contract?
+
+Defaults if no answer: roll to `0.2.0.dev0`, skip 0.1.0 release, add `--list-tools` in batch 1.