afpnews-mcp-server 1.3.11 → 2.0.1

package/.dockerignore

@@ -0,0 +1,6 @@
+node_modules
+build
+.env
+.git
+.continue
+.claude

package/.env.example

@@ -0,0 +1,12 @@
+# AFP API
+APICORE_API_KEY=your-afp-api-key
+APICORE_BASE_URL=                    # optionnel
+
+# Authentification
+JWT_SECRET=                          # générer avec: openssl rand -base64 32  (min 32 chars)
+
+# Serveur
+MCP_SERVER_URL=https://news-mcp.example.com
+PORT=3000                            # optionnel, défaut: 3000
+MCP_TRANSPORT=http                   # stdio ou http
+MCP_SESSION_TTL=3600000              # optionnel, ms, défaut: 1h

package/.serena/project.yml

@@ -0,0 +1,149 @@
+# the name by which the project can be referenced within Serena
+project_name: "afpnews-mcp-server"
+
+
+# list of languages for which language servers are started; choose from:
+#   al                  bash                clojure             cpp                 csharp
+#   csharp_omnisharp    dart                elixir              elm                 erlang
+#   fortran             fsharp              go                  groovy              haskell
+#   java                julia               kotlin              lua                 markdown
+#   matlab              nix                 pascal              perl                php
+#   php_phpactor        powershell          python              python_jedi         r
+#   rego                ruby                ruby_solargraph     rust                scala
+#   swift               terraform           toml                typescript          typescript_vts
+#   vue                 yaml                zig
+#   (This list may be outdated. For the current list, see values of Language enum here:
+#   https://github.com/oraios/serena/blob/main/src/solidlsp/ls_config.py
+#   For some languages, there are alternative language servers, e.g. csharp_omnisharp, ruby_solargraph.)
+# Note:
+#   - For C, use cpp
+#   - For JavaScript, use typescript
+#   - For Free Pascal/Lazarus, use pascal
+# Special requirements:
+#   Some languages require additional setup/installations.
+#   See here for details: https://oraios.github.io/serena/01-about/020_programming-languages.html#language-servers
+# When using multiple languages, the first language server that supports a given file will be used for that file.
+# The first language is the default language and the respective language server will be used as a fallback.
+# Note that when using the JetBrains backend, language servers are not used and this list is correspondingly ignored.
+languages:
+- typescript
+
+# the encoding used by text files in the project
+# For a list of possible encodings, see https://docs.python.org/3.11/library/codecs.html#standard-encodings
+encoding: "utf-8"
+
+# The language backend to use for this project.
+# If not set, the global setting from serena_config.yml is used.
+# Valid values: LSP, JetBrains
+# Note: the backend is fixed at startup. If a project with a different backend
+# is activated post-init, an error will be returned.
+language_backend:
+
+# whether to use project's .gitignore files to ignore files
+ignore_all_files_in_gitignore: true
+
+# list of additional paths to ignore in this project.
+# Same syntax as gitignore, so you can use * and **.
+# Note: global ignored_paths from serena_config.yml are also applied additively.
+ignored_paths: []
+
+# whether the project is in read-only mode
+# If set to true, all editing tools will be disabled and attempts to use them will result in an error
+# Added on 2025-04-18
+read_only: false
+
+# list of tool names to exclude. We recommend not excluding any tools, see the readme for more details.
+# Below is the complete list of tools for convenience.
+# To make sure you have the latest list of tools, and to view their descriptions, 
+# execute `uv run scripts/print_tool_overview.py`.
+#
+#  * `activate_project`: Activates a project by name.
+#  * `check_onboarding_performed`: Checks whether project onboarding was already performed.
+#  * `create_text_file`: Creates/overwrites a file in the project directory.
+#  * `delete_lines`: Deletes a range of lines within a file.
+#  * `delete_memory`: Deletes a memory from Serena's project-specific memory store.
+#  * `execute_shell_command`: Executes a shell command.
+#  * `find_referencing_code_snippets`: Finds code snippets in which the symbol at the given location is referenced.
+#  * `find_referencing_symbols`: Finds symbols that reference the symbol at the given location (optionally filtered by type).
+#  * `find_symbol`: Performs a global (or local) search for symbols with/containing a given name/substring (optionally filtered by type).
+#  * `get_current_config`: Prints the current configuration of the agent, including the active and available projects, tools, contexts, and modes.
+#  * `get_symbols_overview`: Gets an overview of the top-level symbols defined in a given file.
+#  * `initial_instructions`: Gets the initial instructions for the current project.
+#     Should only be used in settings where the system prompt cannot be set,
+#     e.g. in clients you have no control over, like Claude Desktop.
+#  * `insert_after_symbol`: Inserts content after the end of the definition of a given symbol.
+#  * `insert_at_line`: Inserts content at a given line in a file.
+#  * `insert_before_symbol`: Inserts content before the beginning of the definition of a given symbol.
+#  * `list_dir`: Lists files and directories in the given directory (optionally with recursion).
+#  * `list_memories`: Lists memories in Serena's project-specific memory store.
+#  * `onboarding`: Performs onboarding (identifying the project structure and essential tasks, e.g. for testing or building).
+#  * `prepare_for_new_conversation`: Provides instructions for preparing for a new conversation (in order to continue with the necessary context).
+#  * `read_file`: Reads a file within the project directory.
+#  * `read_memory`: Reads the memory with the given name from Serena's project-specific memory store.
+#  * `remove_project`: Removes a project from the Serena configuration.
+#  * `replace_lines`: Replaces a range of lines within a file with new content.
+#  * `replace_symbol_body`: Replaces the full definition of a symbol.
+#  * `restart_language_server`: Restarts the language server, may be necessary when edits not through Serena happen.
+#  * `search_for_pattern`: Performs a search for a pattern in the project.
+#  * `summarize_changes`: Provides instructions for summarizing the changes made to the codebase.
+#  * `switch_modes`: Activates modes by providing a list of their names
+#  * `think_about_collected_information`: Thinking tool for pondering the completeness of collected information.
+#  * `think_about_task_adherence`: Thinking tool for determining whether the agent is still on track with the current task.
+#  * `think_about_whether_you_are_done`: Thinking tool for determining whether the task is truly completed.
+#  * `write_memory`: Writes a named memory (for future reference) to Serena's project-specific memory store.
+excluded_tools: []
+
+# list of tools to include that would otherwise be disabled (particularly optional tools that are disabled by default)
+included_optional_tools: []
+
+# fixed set of tools to use as the base tool set (if non-empty), replacing Serena's default set of tools.
+# This cannot be combined with non-empty excluded_tools or included_optional_tools.
+fixed_tools: []
+
+# list of mode names to that are always to be included in the set of active modes
+# The full set of modes to be activated is base_modes + default_modes.
+# If the setting is undefined, the base_modes from the global configuration (serena_config.yml) apply.
+# Otherwise, this setting overrides the global configuration.
+# Set this to [] to disable base modes for this project.
+# Set this to a list of mode names to always include the respective modes for this project.
+base_modes:
+
+# list of mode names that are to be activated by default.
+# The full set of modes to be activated is base_modes + default_modes.
+# If the setting is undefined, the default_modes from the global configuration (serena_config.yml) apply.
+# Otherwise, this overrides the setting from the global configuration (serena_config.yml).
+# This setting can, in turn, be overridden by CLI parameters (--mode).
+default_modes:
+
+# initial prompt for the project. It will always be given to the LLM upon activating the project
+# (contrary to the memories, which are loaded on demand).
+initial_prompt: ""
+
+# time budget (seconds) per tool call for the retrieval of additional symbol information
+# such as docstrings or parameter information.
+# This overrides the corresponding setting in the global configuration; see the documentation there.
+# If null or missing, use the setting from the global configuration.
+symbol_info_budget:
+
+# list of regex patterns which, when matched, mark a memory entry as read‑only.
+# Extends the list from the global configuration, merging the two lists.
+read_only_memory_patterns: []
+
+# line ending convention to use when writing source files.
+# Possible values: unset (use global setting), "lf", "crlf", or "native" (platform default)
+# This does not affect Serena's own files (e.g. memories and configuration files), which always use native line endings.
+line_ending:
+
+# list of regex patterns for memories to completely ignore.
+# Matching memories will not appear in list_memories or activate_project output
+# and cannot be accessed via read_memory or write_memory.
+# To access ignored memory files, use the read_file tool on the raw file path.
+# Extends the list from the global configuration, merging the two lists.
+# Example: ["_archive/.*", "_episodes/.*"]
+ignored_memory_patterns: []
+
+# advanced configuration option allowing to configure language server-specific options.
+# Maps the language key to the options.
+# Have a look at the docstring of the constructors of the LS implementations within solidlsp (e.g., for C# or PHP) to see which options are available.
+# No documentation on options means no options are available.
+ls_specific_settings: {}

package/CLAUDE.md

@@ -0,0 +1,154 @@
+# CLAUDE.md
+
+This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.
+
+## Project Overview
+
+MCP (Model Context Protocol) server that exposes AFP news tools for LLM-based editors (Continue, Claude Code, etc.). Supports stdio and HTTP (Streamable HTTP) transports.
+
+## Commands
+
+```bash
+bun install         # Install dependencies
+bun src/index.ts    # Run the MCP server (stdio transport by default)
+bun test            # Run tests
+```
+
+## Architecture
+
+TypeScript project organized in `src/`:
+
+```
+src/
+├── index.ts              # Entry point — dispatches to stdio or HTTP transport
+├── mcp-server.ts         # createServer + ServerContext
+├── definitions.ts        # Server-agnostic exports (tools/prompts/resources)
+├── tools/
+│   ├── index.ts          # registerTools() MCP glue
+│   ├── shared.ts         # Shared enums/constants/helpers
+│   ├── search-articles.ts
+│   ├── get-article.ts
+│   ├── find-similar.ts
+│   ├── list-facets.ts
+│   ├── search-media.ts
+│   └── get-media.ts
+├── prompts/
+│   ├── index.ts          # registerPrompts() MCP glue
+│   ├── daily-briefing.ts
+│   ├── comprehensive-analysis.ts
+│   ├── factcheck.ts
+│   └── country-news.ts
+├── resources/
+│   ├── index.ts          # registerResources() MCP glue
+│   └── topics.ts         # TOPICS inline + resource handler
+├── http/
+│   ├── server.ts         # Elysia HTTP server + OAuth2 PKCE auth
+│   ├── tokens.ts         # JWT helpers (encrypt/decrypt AFP tokens)
+│   └── login-page.ts     # OAuth login page + redirect URI helpers
+├── stdio/
+│   └── server.ts         # stdio transport entry
+└── utils/
+    ├── format.ts         # formatDocument, textContent, toolError, truncateIfNeeded, buildPaginationLine
+    ├── format-media.ts   # extractRenditions, formatMediaDocument
+    └── types.ts          # AFPDocument, TextContent, FormattedContent, constants
+```
+
+1. Creates an `ApiCore` client from `afpnews-api` using `APICORE_API_KEY`
+2. Registers MCP tools via `@modelcontextprotocol/sdk`: `afp_search_articles`, `afp_get_article`, `afp_find_similar`, `afp_list_facets`, `afp_search_media`, `afp_get_media`
+3. Authenticates with username/password on first call, then reuses or refreshes the token for subsequent queries
+4. Supports two transports: stdio (default) and HTTP (`MCP_TRANSPORT=http`, uses Elysia + Streamable HTTP with OAuth2 PKCE per-session)
+
+### Definitions-First Pattern
+
+- Tool/prompt/resource files are server-agnostic definitions only.
+- MCP-specific glue (`server.registerTool`, `server.registerPrompt`, `server.registerResource`) lives only in each domain `index.ts`.
+- Aggregated non-MCP exports are provided in `src/definitions.ts`.
+- Published subpath export: `afpnews-mcp-server/definitions`.
+
+## Environment Variables
+
+### Stdio mode
+
+Required:
+- `APICORE_API_KEY` — AFP API key
+- `APICORE_USERNAME` — AFP account username
+- `APICORE_PASSWORD` — AFP account password
+
+Optional:
+- `APICORE_BASE_URL` — AFP API base URL (overrides SDK default)
+
+### HTTP mode
+
+Required:
+- `APICORE_API_KEY` — AFP API key
+- `APICORE_BASE_URL` — AFP API base URL
+- `JWT_SECRET` — Secret for JWT signing/encryption (min 32 characters)
+- `MCP_SERVER_URL` — Public URL of the server (e.g. `https://news-mcp.example.com`)
+- `MCP_TRANSPORT=http`
+
+Optional:
+- `PORT` — HTTP server port (default: 3000)
+- `MCP_SESSION_TTL` — Session duration in milliseconds (default: 3600000 = 1h)
+- `MCP_ALLOWED_REDIRECT_URIS` — Comma-separated list of allowed OAuth redirect URIs
+
+## Key Details
+
+- **Package manager**: bun (v1.3.10)
+- **Runtime**: Bun — TypeScript executed directly, no build step
+- **Module system**: ESM (`"type": "module"`)
+- **Tests**: `bun test`
+- Document types from `afpnews-api` are untyped — the code uses `(doc as any)` casts
+- Package exports:
+  - `afpnews-mcp-server` → MCP runtime entry (`src/index.ts`)
+  - `afpnews-mcp-server/definitions` → pure definitions (`src/definitions.ts`)
+
+## Outils MCP disponibles
+
+| Outil                  | Description                                                        |
+|------------------------|--------------------------------------------------------------------|
+| `afp_search_articles`  | Outil principal de recherche d'articles (filtres + presets + mode fullText) |
+| `afp_get_article`      | Récupération d'un article complet par UNO (texte non tronqué)      |
+| `afp_find_similar`     | Articles similaires (More Like This) à partir d'un UNO             |
+| `afp_list_facets`      | Liste des valeurs d'une facette (slug, genre, country) avec fréquence (preset disponible) |
+| `afp_search_media`     | Recherche de médias AFP (photos, vidéos, graphiques)               |
+| `afp_get_media`        | Récupération d'un média complet par UNO, avec embed base64 optionnel |
+
+### Presets
+
+#### `afp_search_articles.preset`
+
+Presets disponibles:
+- `a-la-une`
+- `agenda`
+- `previsions`
+- `major-stories`
+
+Comportement:
+- Chaque preset applique automatiquement un jeu de filtres `afp_search_articles` adapté.
+- Le preset force `fullText=true`.
+- Le preset peut être affiné via les autres paramètres (`lang`, `size`, etc.), selon les champs déjà fixés par le preset.
+
+#### `afp_list_facets.preset`
+
+Preset disponible:
+- `trending-topics` (équivalent de la logique "topics tendance")
+
+Comportement:
+- Si `preset=trending-topics`, `facet` est ignoré et remplacé en interne par `slug`.
+- Sans preset, `facet` est requis.
+
+### Paramètre `fullText` (tool `afp_search_articles`)
+
+- Type: `boolean`
+- Défaut global: `false`
+- Overridé à `true` par les presets
+
+Règles:
+- `fullText=false` -> extrait (premiers paragraphes)
+- `fullText=true` -> texte complet de la dépêche
+
+## Roadmap — Améliorations fonctionnelles
+
+### Priorité basse
+
+- **Notifications / veille** — exploiter le Notification Center de l'API (`registerService`, `addSubscription`) pour créer des alertes par webhook ou email (bloqué : l'API côté serveur ne fonctionne pas actuellement)

package/Dockerfile

@@ -0,0 +1,19 @@
+FROM oven/bun:1.3.10-alpine
+
+WORKDIR /app
+
+# 1. Installer les deps
+COPY package.json bun.lock ./
+RUN bun install --frozen-lockfile --production
+
+# 2. Copier le code de l’app
+COPY . .
+
+# 3. User non-root
+RUN addgroup -S appgroup && adduser -S appuser -G appgroup
+USER appuser
+
+ENV MCP_TRANSPORT=http
+EXPOSE 3000
+
+CMD ["bun", "src/index.js"]

package/README.md

@@ -6,8 +6,7 @@ The package can also be used as a library without MCP server glue via `afpnews-m
 
 ## Prerequisites
 
-- Node.js 22+
-- [pnpm](https://pnpm.io/)
+- [Bun](https://bun.sh/) 1.3+
 - An AFP API account (API key + username/password)
 
 ## Setup
@@ -15,8 +14,7 @@ The package can also be used as a library without MCP server glue via `afpnews-m
 ```bash
 git clone https://github.com/julesbonnard/afpnews-mcp-server.git
 cd afpnews-mcp-server
-pnpm install
-pnpm run build
+bun install
 ```
 
 Create a `.env` file:
@@ -37,8 +35,8 @@ For local MCP clients like Claude Code or Claude Desktop:
 {
   "mcpServers": {
     "afpnews": {
-      "command": "node",
-      "args": ["build/index.js"],
+      "command": "bun",
+      "args": ["src/index.ts"],
       "cwd": "/absolute/path/to/afpnews-mcp-server",
       "env": {
         "APICORE_API_KEY": "your-api-key",
@@ -52,22 +50,41 @@ For local MCP clients like Claude Code or Claude Desktop:
 
 ### HTTP transport
 
-For remote or multi-user deployments. Each session authenticates independently via HTTP Basic Auth (username/password are your AFP credentials).
+For remote or multi-user deployments. Users authenticate via OAuth2 PKCE using their AFP credentials.
+
+Required environment variables for HTTP mode:
+
+```
+APICORE_API_KEY=your-api-key
+APICORE_BASE_URL=https://api.afp.com
+MCP_SERVER_URL=https://news-mcp.example.com
+JWT_SECRET=a-random-string-of-at-least-32-characters
+MCP_TRANSPORT=http
+PORT=3000
+```
+
+Optional:
+- `MCP_SESSION_TTL` — session duration in milliseconds (default: 3600000 = 1h)
+- `MCP_ALLOWED_REDIRECT_URIS` — comma-separated list of allowed OAuth redirect URIs
 
 ```bash
-MCP_TRANSPORT=http PORT=3000 pnpm run start
+bun src/index.ts
 ```
 
-Notes:
-- Keep `APICORE_API_KEY` set in the server environment (`.env` or runtime env).
-- If you expose the server remotely, use HTTPS.
+If you expose the server remotely, use HTTPS.
 
 ### Docker
 
 ```bash
-pnpm run build
 docker build -t afpnews-mcp .
-docker run -e APICORE_API_KEY=your-api-key -p 3000:3000 afpnews-mcp
+docker run \
+  -e APICORE_API_KEY=your-api-key \
+  -e APICORE_BASE_URL=https://api.afp.com \
+  -e MCP_SERVER_URL=https://news-mcp.example.com \
+  -e JWT_SECRET=your-secret-32-chars-minimum \
+  -e MCP_TRANSPORT=http \
+  -p 3000:3000 \
+  afpnews-mcp
 ```
 
 ### As a library (without MCP server dependency)
@@ -103,6 +120,8 @@ Each definition is framework-agnostic:
 | `afp_get_article` | Get a full article by its UNO identifier |
 | `afp_find_similar` | Find similar articles (More Like This) from a UNO |
 | `afp_list_facets` | List facet values (topics, genres, countries) with frequency counts |
+| `afp_search_media` | Search AFP media documents (photos, videos, graphics) |
+| `afp_get_media` | Get a full media document by UNO, with optional base64 image embed |
 
 ### Search presets
 
@@ -119,7 +138,11 @@ The `afp_search_articles` tool supports presets that apply predefined filters:
 
 ### Full text
 
-By default, `afp_search_articles` returns excerpts (first 4 paragraphs). Set `fullText: true` to get the complete article body. Presets default to full text.
+By default, `afp_search_articles` returns excerpts (first 2 paragraphs). Set `fullText: true` to get the complete article body. Presets default to full text.
+
+### Pagination
+
+Use `offset` to paginate through results (e.g. `offset: 10` to skip the first 10). For large chronological scans, prefer narrowing `dateFrom`/`dateTo` ranges in `facets` over high offsets. Keep `size` small (10–20) for best performance.
 
 ## Prompts
 
@@ -139,9 +162,8 @@ By default, `afp_search_articles` returns excerpts (first 4 paragraphs). Set `fu
 ## Development
 
 ```bash
-pnpm install
-pnpm run build
-pnpm test
+bun install
+bun test
 ```
 
 ## Internal Architecture