Skip to content

Commit c525fe8

Browse files
committed
feat: Enhance README and concepts documentation with unified SDK explanation
1 parent 19ec9b5 commit c525fe8

File tree

2 files changed

+20
-0
lines changed

2 files changed

+20
-0
lines changed

README.md

Lines changed: 18 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -10,11 +10,14 @@ A schema-driven module development framework that makes every interface naturall
1010

1111
**apcore is a protocol specification.** Language implementations are maintained in separate repositories — see [Implementations](#implementations).
1212

13+
The growing number of fragmented MCP implementations across the ecosystem proves the demand is real. apcore is the only solution that provides a **complete SDK** with a **unified standard** — enforced schema, behavioral annotations, access control, audit trails, and cross-language consistency. It doesn't replace any project's AI capabilities; it brings them all under one standard.
14+
1315
---
1416

1517
## Table of Contents
1618

1719
- [What is apcore?](#what-is-apcore)
20+
- [Why Not Just Use Existing MCP Solutions?](#why-not-just-use-existing-mcp-solutions)
1821
- [Why AI-Perceivable?](#why-ai-perceivable)
1922
- [Core Principles](#core-principles)
2023
- [Architecture Overview](#architecture-overview)
@@ -66,6 +69,21 @@ apcore is a **universal module development framework** that makes every module n
6669

6770
**Not just an AI framework, but a universal framework that is naturally AI-Perceivable.**
6871

72+
### Why Not Just Use Existing MCP Solutions?
73+
74+
Today, many projects build their own MCP servers independently — Stripe has one, TipTap has one, NestJS has one. Each uses different interfaces, different standards, and none provides a programmable SDK. The result is a fragmented ecosystem where developers must learn a new approach for every integration.
75+
76+
apcore takes a different path: **SDK-first, standard-unified**.
77+
78+
| | Fragmented MCP Solutions | apcore |
79+
|---|---|---|
80+
| **Programmable SDK** | No — only MCP servers | Yes — `apcore-python`, `apcore-typescript` |
81+
| **Unified Standard** | No — each project rolls its own | Yes — same schema, annotations, ACL across all integrations |
82+
| **Behavioral Annotations** | None or minimal | `readonly`, `destructive`, `requires_approval`, `idempotent`, `open_world` |
83+
| **Access Control** | None | Pattern-based ACL with role support |
84+
| **Audit Trail** | None | Built-in tracing, metrics, structured logging |
85+
| **Cross-Language** | Per-language silos | Python and TypeScript with identical behavior |
86+
6987
### Core Problem
7088

7189
Traditional module development faces a fundamental contradiction:

docs/concepts.md

Lines changed: 2 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -6,6 +6,8 @@
66

77
### 1.1 Why Do We Need apcore?
88

9+
The growing number of fragmented MCP implementations across the ecosystem proves the demand is real. apcore is the only solution that provides a **complete SDK** with a **unified standard** — enforced schema, behavioral annotations, access control, audit trails, and cross-language consistency. It doesn't replace any project's AI capabilities; it brings them all under one standard.
10+
911
**Problems with traditional module development:**
1012

1113
```python

0 commit comments

Comments
 (0)