<div align="center"> <img src="./apcore-mcp-logo.svg" alt="apcore-mcp logo" width="200"/> </div>

apcore-mcp

Build once, invoke by Code or AI.

apcore-mcp turns any apcore-based project into an MCP Server and OpenAI tool provider — with zero code changes to your existing project.

┌──────────────────┐
│  django-apcore   │  ← your existing apcore project (unchanged)
│  nestjs-apcore   │
│  tiptap-apcore   │
│  ...             │
└────────┬─────────┘
         │  extensions directory
         ▼
┌──────────────────┐
│    apcore-mcp    │  ← just install & point to extensions dir
└───┬──────────┬───┘
    │          │
    ▼          ▼
  MCP       OpenAI
 Server      Tools

---

Installation

=== "🐍 Python"

```bash
pip install apcore-mcp
```
*Requires Python 3.11+ and apcore 0.21.0+ (optional `[markdown]` extra: apcore-toolkit 0.6.0+).*

=== "📘 TypeScript"

```bash
npm install apcore-mcp
```
*Requires Node.js 18+ and apcore-js >=0.21.1 (optional peer: apcore-toolkit >=0.6.1).*

=== "🦀 Rust"

```bash
cargo add apcore-mcp
```
*Requires Rust 1.75+ and apcore = "0.21.0", apcore-toolkit = "0.6.0".*

---

Quick Start

1. Serve your modules via MCP

=== "🐍 Python"

```python
from apcore_mcp import APCoreMCP

mcp = APCoreMCP("./extensions")

# Launch as MCP Server over stdio
mcp.serve()

# Or with HTTP + Explorer UI
mcp.serve(transport="streamable-http", port=8000, explorer=True)
```

=== "📘 TypeScript"

```typescript
import { serve } from "apcore-mcp";

// Launch MCP server over stdio
await serve("./extensions");

// Launch over Streamable HTTP with Explorer UI
await serve("./extensions", {
  transport: "streamable-http",
  port: 8000,
  explorer: true,
});
```

=== "🦀 Rust"

```rust
use apcore_mcp::APCoreMCP;

// Launch MCP server over stdio
let mcp = APCoreMCP::builder()
    .backend("./extensions")
    .build()?;
mcp.serve()?;
```

=== "💻 CLI"

```bash
# stdio (default)
apcore-mcp --extensions-dir ./extensions

# Streamable HTTP with Explorer UI
apcore-mcp --extensions-dir ./extensions --transport streamable-http --port 8000 --explorer
```

2. Export as OpenAI Tools

=== "🐍 Python"

```python
from apcore_mcp import APCoreMCP

mcp = APCoreMCP("./extensions")
tools = mcp.to_openai_tools()
```

=== "📘 TypeScript"

```typescript
import { APCoreMCP } from "apcore-mcp";

const mcp = new APCoreMCP("./extensions");
const tools = mcp.toOpenaiTools();
```

=== "🦀 Rust"

```rust
use apcore_mcp::APCoreMCP;

let mcp = APCoreMCP::builder()
    .backend("./extensions")
    .build()?;
let tools = mcp.to_openai_tools(false, true)?;
```

---

Key Features

• 🚀 Zero Intrusion: Your apcore project needs no code changes, no imports, and no extra dependencies.
• 🔍 Auto-discovery: Point to an extensions directory, and everything is automatically discovered and exposed.
• 🌐 Triple Transport: Supports stdio (for local LLMs), Streamable HTTP, and SSE.
• 🛠️ Tool Explorer: Browser-based UI to browse schemas and test tools interactively (like Swagger UI for MCP).
• 🛡️ Security: Built-in JWT authentication, PEM key support, and runtime approval elicitation.
• 🤖 AI Optimized: Enriched metadata (x-when-to-use), error sanitization with AI guidance, and strict mode for OpenAI.
• 🔄 Dynamic: Reflects module registrations/unregistrations at runtime without restarting.

---

Architecture

apcore-mcp acts as a protocol-specific adapter on top of the apcore Registry, mapping its metadata to MCP and OpenAI standards:

| apcore Concept | MCP Mapping | OpenAI Mapping | |----------------|-------------|----------------| | module_id | Tool name | name (dash-normalized) | | description | Tool description | description | | input_schema | inputSchema | parameters | | annotations | ToolAnnotations hints | Description suffixes (optional) | | metadata | _meta fields | — |

---

Features & Specifications

The project is architected as a set of modular features, each with its own specification to ensure consistency across languages:

• Feature Overview — Implementation roadmap & dependencies
• Schema Converter — Reference resolution for AI protocols
• Annotation Mapper — Behavioral hint translation
• Execution Router — Dispatcher for the 11-step pipeline
• Error Mapper — Protocol-compliant error feedback
• MCP Server Factory — Core server builder
• OpenAI Converter — Tool exporter for OpenAI
• Extension Bridge — Wires apcore ExtensionManager into MCP pipeline
• Transport Manager — Stdio/HTTP connectivity
• Registry Listener — Hot-reloading capabilities
• JWT Authenticator — Bearer token security
• Approval Handler — Human-in-the-loop elicitation
• Async Task Bridge — Routes async-hinted modules to apcore's AsyncTaskManager
• Explorer UI — Interactive dev dashboard
• Markdown — Rich Markdown tool descriptions via apcore-toolkit (v0.15+)

---

Documentation

• Full Documentation Site
• Getting Started Guide — Installation and basic setup
• PRD
• SRS
• Tech Design

---

Implementations

| Language | Repository | Package | Status | |----------|-----------|---------|--------| | Python | apcore-mcp-python | pip install apcore-mcp | ✅ v0.15.0 | | TypeScript | apcore-mcp-typescript | npm install apcore-mcp | ✅ v0.15.0 | | Rust | apcore-mcp-rust | cargo add apcore-mcp | ✅ v0.15.0 | | Go | apcore-mcp-go | — | Planned |

License

This project is licensed under the Apache License 2.0. See the LICENSE file for details.