docs(server-core): add README with package overview and usage example

.changeset/server-core-readme.md

@@ -0,0 +1,5 @@
+---
+"@voltagent/server-core": patch
+---
+
+Add README documentation

packages/server-core/README.md

@@ -0,0 +1,178 @@
+<div align="center">
+<a href="https://voltagent.dev/">
+<img width="1500" height="276" alt="voltagent" src="https://github.com/user-attachments/assets/d9ad69bd-b905-42a3-81af-99a0581348c0" />
+</a>
+
+<h3 align="center">
+AI Agent Engineering Platform
+</h3>
+
+<div align="center">
+    <a href="https://voltagent.dev">Home Page</a> |
+    <a href="https://voltagent.dev/docs/">Documentation</a> |
+    <a href="https://github.com/voltagent/voltagent/tree/main/examples">Examples</a>
+</div>
+</div>
+
+<br/>
+
+<div align="center">
+
+[![GitHub issues](https://img.shields.io/github/issues/voltagent/voltagent)](https://github.com/voltagent/voltagent/issues)
+[![GitHub pull requests](https://img.shields.io/github/issues-pr/voltagent/voltagent)](https://github.com/voltagent/voltagent/pulls)
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
+[![npm version](https://img.shields.io/npm/v/@voltagent/server-core.svg)](https://www.npmjs.com/package/@voltagent/server-core)
+[![npm downloads](https://img.shields.io/npm/dm/@voltagent/server-core.svg)](https://www.npmjs.com/package/@voltagent/server-core)
+[![Discord](https://img.shields.io/discord/1361559153780195478.svg?label=&logo=discord&logoColor=ffffff&color=7389D8&labelColor=6A7EC2)](https://s.voltagent.dev/discord)
+
+</div>
+
+## @voltagent/server-core
+
+Framework-agnostic server core for VoltAgent. This package provides the shared infrastructure — route definitions, request handlers, WebSocket support, authentication utilities, MCP/A2A protocol helpers, and a base server provider — that all VoltAgent server adapters (e.g. `@voltagent/server-hono`) build on top of.
+
+You typically do not use this package directly. Instead, choose a server adapter for your framework (such as `@voltagent/server-hono`) and pass it to the `VoltAgent` constructor. If you are building a **custom server adapter**, this package gives you everything you need.
+
+---
+
+## Key Exports
+
+### Base Server Provider
+
+`BaseServerProvider` — Abstract class that handles the common server lifecycle (port allocation, WebSocket setup, graceful shutdown, startup banner). Extend it when building a custom adapter.
+
+```ts
+import { BaseServerProvider } from "@voltagent/server-core";
+```
+
+### Route Definitions
+
+Pre-built, framework-agnostic route metadata objects you can use to register routes in any HTTP framework:
+
+| Export                        | Routes covered                               |
+| ----------------------------- | -------------------------------------------- |
+| `AGENT_ROUTES`                | Agent management and generation              |
+| `WORKFLOW_ROUTES`             | Workflow execute / stream / suspend / resume |
+| `TOOL_ROUTES`                 | Tool listing and direct execution            |
+| `MEMORY_ROUTES`               | Conversation and message management          |
+| `LOG_ROUTES`                  | Log retrieval                                |
+| `OBSERVABILITY_ROUTES`        | Traces, spans, and observability status      |
+| `OBSERVABILITY_MEMORY_ROUTES` | Memory inspection for observability          |
+| `MCP_ROUTES`                  | Model Context Protocol server endpoints      |
+| `A2A_ROUTES`                  | Agent-to-Agent protocol endpoints            |
+| `ALL_ROUTES`                  | All of the above combined                    |
+
+Helper functions: `getAllRoutesArray()`, `getRoutesByTag(tag)`.
+
+### Request Handlers
+
+Framework-agnostic handler functions. Each handler receives a `ServerProviderDeps` context and returns a serialisable response object, making them easy to wrap in any HTTP framework:
+
+- **Agent handlers** — `handleGenerateText`, `handleStreamText`, `handleChatStream`, `handleResumeChatStream`, `handleGenerateObject`, `handleStreamObject`
+- **Workflow handlers** — `handleGetWorkflows`, `handleGetWorkflow`, `handleExecuteWorkflow`, `handleStreamWorkflow`, `handleAttachWorkflowStream`, `handleSuspendWorkflow`, `handleResumeWorkflow`, `handleListWorkflowRuns`, `handleGetWorkflowState`
+- **Tool handlers** — `handleListTools`, `handleExecuteTool`
+- **Memory handlers** — `handleListMemoryConversations`, `handleCreateMemoryConversation`, `handleSaveMemoryMessages`, and more
+- **Observability handlers** — `getTracesHandler`, `getTraceByIdHandler`, `getObservabilityStatusHandler`, and more
+- **Log handlers** — `handleGetLogs`
+
+### Authentication
+
+Plug-in auth via the `AuthProvider` interface. A built-in JWT provider is included:
+
+```ts
+import { jwtAuth, createJWT } from "@voltagent/server-core";
+```
+
+### WebSocket Utilities
+
+`createWebSocketServer`, `setupWebSocketUpgrade` — set up real-time log and observability streaming over WebSocket.
+
+### MCP & A2A Protocol Helpers
+
+- `MCPServerRegistry`, `listMcpServers`, `lookupMcpServer` — register and resolve MCP servers
+- `A2AServerRegistry`, `listA2AServers`, `lookupA2AServer`, `executeA2ARequest` — Agent-to-Agent protocol support
+
+### App Setup Utilities
+
+`getOpenApiDoc`, `shouldEnableSwaggerUI`, `getOrCreateLogger`, `DEFAULT_CORS_OPTIONS` — helpers shared by all server adapters.
+
+### Edge Entry Point
+
+A lighter entry point for edge runtimes (e.g. Cloudflare Workers, Vercel Edge) is available at the `./edge` export:
+
+```ts
+import { AGENT_ROUTES, handleGenerateText } from "@voltagent/server-core/edge";
+```
+
+---
+
+## Usage Example — Custom Server Adapter
+
+The snippet below shows the minimum required to build a custom server adapter on top of `@voltagent/server-core`:
+
+```typescript
+import { createServer, type Server } from "node:http";
+import { BaseServerProvider, type ServerProviderConfig } from "@voltagent/server-core";
+import type { ServerProviderDeps } from "@voltagent/core";
+
+export class MyCustomServerProvider extends BaseServerProvider {
+  constructor(deps: ServerProviderDeps, config: ServerProviderConfig = {}) {
+    super(deps, config);
+  }
+
+  protected async startServer(port: number): Promise<Server> {
+    const server = createServer((req, res) => {
+      // Route incoming requests to the framework-agnostic handlers
+      res.writeHead(404);
+      res.end("Not found");
+    });
+
+    await new Promise<void>((resolve) => server.listen(port, resolve));
+    return server;
+  }
+
+  protected async stopServer(): Promise<void> {
+    await new Promise<void>((resolve, reject) => {
+      this.server?.close((err) => (err ? reject(err) : resolve()));
+    });
+  }
+}
+
+// Factory function consumed by VoltAgent
+export function myCustomServer(config?: ServerProviderConfig) {
+  return (deps: ServerProviderDeps) => new MyCustomServerProvider(deps, config);
+}
+```
+
+Pass the factory to `VoltAgent`:
+
+```typescript
+import { VoltAgent, Agent } from "@voltagent/core";
+import { openai } from "@ai-sdk/openai";
+import { myCustomServer } from "./my-custom-server";
+
+const agent = new Agent({
+  name: "my-agent",
+  instructions: "A helpful assistant",
+  model: openai("gpt-4o-mini"),
+});
+
+new VoltAgent({
+  agents: { agent },
+  server: myCustomServer({ port: 3141 }),
+});
+```
+
+For a complete, production-ready server adapter see [`@voltagent/server-hono`](https://github.com/VoltAgent/voltagent/tree/main/packages/server-hono).
+
+---
+
+## Documentation
+
+- [VoltAgent Documentation](https://voltagent.dev/docs/)
+- [Agent Overview](https://voltagent.dev/docs/agents/overview/)
+- [MCP Integration](https://voltagent.dev/docs/agents/mcp/)
+
+## License
+
+Licensed under the MIT License, Copyright © 2026-present VoltAgent.